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PREFACE 


Primary reference material for user and subsystem programming on the 
Multics system is contained in six manuals. The manuals are collectively 
referred to as the Multics Programmers' Manual (MPM). Throughout this manual, 
references are frequently made to the MPM. For convenience, these references 
will be as follows: 


Document Referred To In Text As 


Reference Guide MPM Reference Guide 
(Order No. AG91) 


Commands and Active Functions MPM Commands 


(Order No. AG92) 


Communications Input/Output MPM Communications I/0 
(Order No. CC92) 


Subroutines MPM Subroutines 
(Order No. AG93) 


Subsystem Writers! Guide MPM Subsystem Writers' Guide 
(Order No. AK92) 
Peripheral Input/Output MPM Peripheral I/0 


(Order No. AX49 


The MPM Reference Guide contains general information about’ the Multics 
command and programming environments. It also defines items used throughout the 
rest of the MPM. And, in addition, describes such subjects as the command 
language, the storage system, and the input/output system. . 


The MPM Commands is organized into four sections. Section 1 contains a 
list of the Multics command repertoire, arranged functionally. Section 2 
describes the active functions. Section 3 contains descriptions of standard 
Multics commands, including the calling sequence and usage of each command. 
Section 4 describes the requests used to gain access to the system. 


The MPM Peripheral I/0 manual contains descriptions of commands and 
subroutines used to perform peripheral I/O. Included in this manual are 
commands and subroutines that manipulate tapes and disks as I/0 devices. 


The MPM Communications I/O manual contains information about the Multics 
communications system. Included are sections on the commands, subroutines, and 
I/0 modules used to manipulate communications I/0. Special purpose 
communications I/0, such as binary synchronous communication, is also included. 
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The MPM Communications I/O manual contains information about the Multics 
communications system. Included are sections on the commands, subroutines, and 
I/O modules used to manipulate communications I/0. Special purpose communications 
I/O, such as binary synchronous communication, is also included. 


The MPM Subroutines is organized into three sections. Section 1 contains a 
list of the subroutine repertoire, arranged functionally. Section 2 contains 
descriptions of the standard Multics subroutines, including the declare statement, 
the calling sequence, and usage of each. Section 3 contains the descriptions of 
the I/0 modules. 


The MPM Subsystem Writers' Guide is a reference of interest to compiler 
‘writers and writers of sophisticated subsystems. It documents user-accessible 
modules that allow the user to bypass standard Multics facilities. The interfaces 
thus documented are a level deeper into the system than those required by the 
majority of users. 


Examples of specialized subsystems for which construction would require 
reference to the MPM Subsystem Writers' Guide are: 


* A subsystem that precisely imitates the command environment of some 
system other than Multics. 


* A subsystem intended to enforce restrictions on the services available 
to a set of users (e.g., an APL-only subsystem for use in an academic 
elass). 

& A subsystem that protects some kind of information in a way not easily 


expressible with ordinary access control lists (e.g., a proprietary 
linear programming system, or an administrative data base system that 
permits access only to program-defined, aggregated information such as 
averages and correlations). 


The MPM Subsystem Writers' Guide provides the advanced Multics user with a 
selection of some of the internal interfaces used to construct the standard 
Multics user interface. It also describes some specialized tools helpful to the 
advanced subsystem writer. 


The facilities described here are subject to changes and improvements in 
their interface specifications. Further, at the level of the system presented 
by many of these interfaces, it is difficult to avoid far-reaching subsystem 
changes when these interfaces change. Thus, the subsystem writer is cautioned 
against the unnecessary use of the interfaces described in this manual. 


Most interfaces described here should be used only if there is a need to 
bypass normal Multics procedures; i.e., in using one of these interfaces, the 
user risks giving up somé of the desirable characteristics of Multics. For 
example, the standard Multics interface presents a consistency of style and 
interpretation to the user that the subsystem writer may find difficult to duplicate 
and maintain. Therefore, the subsystem writer should be cautious about 
unintentionally introducing different, and possibly confusing, styles and 
interpretations when bypassing a standard function. 


However, one of the objectives of Multics is to allow the knowledgeable 
user to construct subsystems of almost any specification. The content of the 
MPM Subsystem Writers! Guide, applied with care, is intended to help fulfill 
this objective. 
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Several cross-reference facilities in the MPM help locate information: 


@ Each manual has a table of contents that identifies the material (either 
the name of the section and subsection or an alphabetically ordered 
list of command and subroutine names) by page number. 


e Each manual contains an index that lists items by name and page number. 


Changes and Additions to MPM Subsystem Writers' Guide, AK92, Rev. 2, Addendum D 


The following subroutine and entry point descriptions are new to this manual 
and do not contain change bars. 


get external variable set ext variable $locate 

hes $get uid seg ~ sus signal handler 

msf manager $msf get ptr sus signal handler $reconnect ec enable 
read password $switch sus Signal handler $reconnect ec disable 


set_ext_variable_ 
The signal command is new to this manual and does not contain change bars. 


The display component name and 2ist_ external UETETHaTyariabies commands were 
inadvertently omitted from the previous addendum. ey are included in this 


addendum, and do not contain change bars. 
The mode string subroutine has been moved to the MPM Subroutines manual. 


The following subroutine and entry point descriptions are obsolete and have 
been deleted. 


convert ipe code resource control $set status 


resource control $assign resource control $sunassign 
resource control $get status 


Throughout this manual change bars indicate technical additions and changes, 
and asterisks indicate deletions. 
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SECTION 1 


MULTICS STANDARD OBJECT SEGMENT 


A Multics object segment contains object code generated by a translator and 
linkage information that is used by the dynamic linking mechanism to resolve 
intersegment references. (See "Dynamic Linking" in the MPM Reference Guide.) 
The most common examples of object segments are procedure segments and data 
segments. 


Format requirements for an object segment are primarily associated with 
external interfaces; thus, translator designers are permitted a great amount of 
freedom in the area of code and data generation. The format contains certain 
redundancies and unusual data structures; these are a byproduct of maintaining 
upward compatibility with earlier object segment formats. The dynamic linking 
mechanism and the standard object segment manipulation tools assume that all 
object segments are standard object segments. 


FORMAT OF AN OBJECT SEGMENT 


An object segment is divided into six sections that usually appear in the 
following order: 


text 

definition 

linkage 

static (if present) 
symbol 

break map (if present) 


The type of information contained in each of the six sections is summarized 
below: 


Los text 
contains only pure parts of the object segment (instructions and 


read-only data). It ean also contain relative pointers to. the 
definition, linkage and symbol sections. 


eae definition 

contains only nonexecutable, read-only symbolic information used for 
dynamic linking and symbolic debugging. Since it is assumed tnat the 
definition section is infrequently referenced (as opposed to’ the 
constantly referenced text section), it should not be used as a 
repository for read-only constants referenced during the execution of 
the text section. The definition section can sometimes (as in the 
case of an object segment generated by the binder) be structured into 
definition blocks that are threaded together. 


ee linkage 
contains the impure (i.e., modified during the program's execution) 
nonexecutable parts of the object segment and may consist of two types 
of data: 
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a. links modified at run time by the Multics linker to contain the 
machine address of external references, and possibly 


Dis data items to be allocated on a per-process basis such as the 
internal static storage of PL/I procedures. 


4. static 
contains the data items to be allocated on a per-process basis. The 
static storage may be included in the linkage section in which case 
there is no explicit separate static section. 


he break map 
contains information used by the debuggers to locate breakpoints in 
the object segment. This section is generated by the debuggers rather 
than the translator and only when the segment currently contains 
breakpoints. Its internal format is of interest only to the 
debuggers. 


6% symbol 
contains all generated items of information that do not belong in the 
first five sections such as the language processor's symbol tree and 
historical and relocation information. The symbol section may be 
further structured into variable length symbol blocks threaded to form 
a list. The symbol section contains only pure information. 


The text, definition, and symbol sections are shared by all processes that 
reference an object segment. Usually, a copy of the linkage section is made 
when an object segment is first referenced in a process. That is, the linkage 
section is a per=-process data base. The original linkage section serves only as 
a copying template. An exception is made for some system programs whose link 
addresses are filled in at system initialization time. Their linkage sections 
are shared by everyone who wants to use the supplied addresses. When these 
programs have data items in internal storage, they have a separate static 
section template that is copied once per process. See the MPM Reference Guide 
and "Standard Stack and Linkage Area Formats" in Section 2 of this document. 
Normally, a segment containing break map information is in the state of being 
debugged and is not used by more than one process. 


The object segment also contains an object map that contains the offsets 
and lengths of each of the sections. The object map can be located immediately 
before or immediately after any of the six sections. Translators normally place 
it immediately after the symbol section. The last word of every object segment 
must contain a left-justified 18-bit relative pointer to the object map. 


STRUCTURE OF THE TEXT SECTION 


The text section is basically unstructured, containing the machine-language 
representation of a symbolic algorithm and/or pure data. Its length is usually 
an even number of words. 


Two of the items that can appear within the text section have standard 
formats: the entry sequence and the gate segment entry point transfer vector. 
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Entry Sequence 


A standard entry sequence is usually provided for every externally 


accessible procedure entry point inan object segment. A standard entry 
sequence has the following format, defined by the system include file 
entry sequence _info.inel.pli: 


del 1 parm dese ptrs aligned, 
2 n_args fixed bin(i8) unaligned unsigned, 
2 descriptor relp (num_deses refer(parm_ dese ptrs.n_args)) 


bit(18) unaligned, 


del 1 entry_sequence aligned, 
2 desecr_relp offset bit(18) unaligned, 
2 reserved bit(18) unaligned, 
2 def _relp bit(18) unaligned, 
2 flags unaligned, 
3 basic_indicator bit(1) unaligned, 
3 revision_1 bit(1) unaligned, 
3 has_descriptors bit(1) unaligned, 
3 variable bit(1) unaligned, 
3 function bit(1) unaligned, 
3 pad bit(13) unaligned, 
2 code_sequence bit(36) aligned; 
where: 
1. n_args 
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is the number of arguments expected by this external entry point. 
This item is optional and is valid only if the flag has descriptors 
equals "1"b. 


descriptor _relp 
is an array of pointers (relative to the base of the text section) 
to the descriptors of the corresponding entry point parameters. 
This item is optional and is valid only if the flag has descriptors 
equals "1"b. See "Parameter Descriptors" in Section 2. 


deser_relp offset 
is the offset (relative to the base of the text section) of the 
n_args item. This item is optional and is valid only if the flag 
has descriptors equals "1"b. 


reserved 
is reserved for future use and must be "O"b. 


def relp 
is an offset (relative to the base of the definition section) to the 
definition of this entry point. Thus, given a pointer to an entry 
point, it is possible to reconstruct its symbolic name for purposes 
such as diagnostics or debugging. 


flags 
contains 18 binary indicators that provide information about this 
entry point. 


basic indicator 
ie eae} this is the entry point of a BASIC program 
OND this is not the entry point of a BASIC program 


revision 1 

wey all of the entry's parameter descriptor information is with 
the entry sequence, i.e., none is in the definition 

OD parameter descriptor information, if any, is with the 
definition 
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has descriptors 
oat ll 3) the entry has parameter descriptors; i.e., items n_args, 


descriptor relp and descr _relp offset contain valid 
information = 


"O"b the entry does not have parameter descriptors 


variable 
may the entry expects arguments whose number and types are 
variable 


"O"b the number and type of arguments, if any, are not variable 


function 
A SD the last parameter is to be returned by this entry 
"O"b the last parameter is not to be returned by this entry 


pad 
the last parameter is not to be returned by this entry 


7. code sequence 
is any sequence of machine instructions satisfying Multics standard 


calling conventions. See "Subroutine Calling Sequences" in 
Section 2. 


The value (i.e., offset within the text section) of the entry point 
corresponds to the address of the code sequence item. (The value is stored in 
the formal definition of the entry point. See "Structure of the Definition" 
below.) Thus, if entry_offset is the value of the entry point enti, then the 
def relp item pointing to the definition for enti is located at word 
(entry_offset minus 1). 


Gate Segment Entry Point Transfer Vector 


For protection purposes, control must not be passed to a gate procedure at 
other than its defined entry points. To enforce this restriction, the first n 
words of a gate segment with n entry points must be an entry point transfer 
vector. That is, the kth word (0 < k < n-1) must be a transfer instruction to 
the kth entry point (i.e., a transfer to the code_sequence item of a standard 
entry sequence as described above). In this case, the value of the kth entry 
point is the offset of the kth transfer instruction (i-e., word k of the 
segment) rather than the offset of the code sequence item of the kth entry 
point. 


To ensure that only these entries can be used, the hardware enforced entry 
bound of the gate segment must be set so that the segment can be entered only at 
the first n locations. 


STRUCTURE OF THE DEFINITION SECTION 


ES 


The definition section of an object segment contains pure information that 
is used by the dynamic linking mechanisn. 


The definition section consists of a header pointing to a linked list of 
items describing the externally accessible named items of the object segment, 
followed by an unstructured area containing information describing the 
externally accessible named items of other object segments referenced by this 
object segment. The linked list is known as the definition list. The items on 
the list are known as definitions. The unstructured area contains expression 
words, type pairs, trap words, trap procedure information, and the symbolic 
names associated with external references. 
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A definition specifies the name of an externally accessible named item and 
its location in the object segment. The definition list consists of one or more 
definition blocks each of which consists of one or more class-3 definitions 
followed by zero or more definitions that are not class-3 (see "Definition 
Section Header" below for format). Normally, unbound object segments contain 
one definition block, while bound segments contain one definition block for 
every component object segment. 
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Optionally, the definition section can contain a definition hash table. If 
present, . the hash table is used by the linker to expedite the search for a 
definition. 


The information in the unstructured area of the definition section is used 
at runtime in conjunction with information in the linkage section to resolve the 
external references made by the object segment. This information is 
conceptually part of the linkage section, but is stored in the definition 
section so it can be shared among all the users of the segment. 


Figure 1-1 shows the structure of the definition section. For more 
information concerning the interpretation of the information in the definition 
section see "Dynamic Linking" in Section 4 in MPM Reference Guide. 


Character strings in the definition section are stored in ALM "ace" format. 
This format is described by the following PL/I declaration, defined by the 
system include file acec.inél.pll: 


del 1 ace based aligned, 
2 num_chars fixed bin(9) unsigned unaligned, 
2 string char(0 refer(acc.num_chars)) unaligned; 


The first nine bits of the string contain the length of the string. Unused bits 
of the last word of the string must be zero. Such a structure is referred to as 
an ace string. 


The following paragraphs describe the formats of the various items in the 
definition section. 
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Block 1 


segname_ thread 
string_ ptr defblock_ ptr 


Header 


Block 2 
string_ ptr defblock_ ptr 


fe segnametiveed [ses 
defblock ptr 
maa! 


value 


wwe fmm meen eee wee ee eee emma an se ee se ee 


Block 3 


defblock_ptt 
forward [backward 
a Roe Saeeaeea = aes AE, 


segname_ ptr 


| string ptr 


all zero word 


Figure 1-1. Sample Definition List 
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Definition Section Header 


The def 


inition section header resides at the base of the definition section 


and contains an offset (relative to the base of the definition section) to the 
beginning of the definition list. 


where 


Ts 


12/79 


del id 


NO PON Po 


° 
° 


def_lis 


unused 


ef header aligned, 

def list relp ittls) unaligned, 

unused — bit(18) unaligned, | 
hash table relp bit(18) unaligned, 

flags unaligned, 

3 new format bit(1) unaligned initial ('1"b), 

3 ignore bit(1) unaligned initial ("1"b), 

3 unused bit(16) unaligned; 

t_relp 


is arelative pointer to the first definition in the definition 
list. 


is reserved for future use and must be "O"b. 


hash table relp 


flags 


is a relative pointer to the beginning of the definition hash table. 
If no definition hash table is present, this pointer must be "O"b. 


contains 18 binary indicators that provide information about this 
definition section: 


new format 
ue Mad 0 definition section has new format 
"OM definition section has old format 


ignore 

TD if new format equals "1"b, the Multics linker ignores this 
definition. 

a 9 is an old format definition 


unused 
is reserved for future use and must be "O"b 


A definition that is not class-3 has the following format, defined by the | 
system include file definition.incl.pli: 


ded’ 1 


NOP PP 


NM POD PO Po 


efinition aligned, 

forward pitts) unaligned, | 
backward bit(18) unaligned, 

value bit(18) unaligned, 

flags unaligned, 

3 new bit(1) unaligned, | I 
3 ignore -  pit(1) unaligned, 

3 entry pit(1) unaligned, i 
3 retain bit(1) unaligned, 

3 argcount bit(1) unaligned, 

3 descriptors bit(1) unaligned, l 
3 unused bit(9) unaligned, 

class bit(3) unaligned, 

symbol bit(18) unaligned, | 
segname bit(18) unaligned, 

n args bit(18) unaligned, 

descriptor relp(O refer(n_args)) bit(18) unaligned; 
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where 


fou. 


J >. 


3. 
4. 
I 
I 
| 
5. 
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forward 


value 


class 


is a thread (relative to the base of the definition section) to the 
next definition. The thread terminates when it points to a word 
that is 0. This thread provides a single sequential list of all the 
definitions within the definition section. 


backward 


is a thread (relative to the base of the definition section) to the 
preceding definition. 


is the offset, within the section designated by the class variable 
(described below), of this symbolic definition. 


contains 15 binary indicators that provide additional information 
about this definition: 


new 
WEED definition section has new format 
"OMD definition section has old format 


ignore 

se le definition does not represent an external symbol and is, 
therefore, ignored by the Multics linker 

"OOD definition represents an external symbol 


entry 

bie Aa ©) definition of an entry point (a variable reference through a 
transfer of control instruction) 

eS Ae definition of an external symbol that does not represent a 
standard entry point 


retain 

bs os 3, definition must be retained in the object segment (by the 
binder) 

"O'"b definition can be deleted from the object segment (by the 
binder) 

argcount 

ei ale) (obsolete) definition includes a count of the argument 
descriptors (AeSes item n args below contains valid 


tunFarmatinn 
aise Ua maduryii, 


VO" no argument descriptor information is associated with the 


definition 
descriptors 
WAND (obsolete) definition includes an array oof argument 


descriptor (i.e., items nargs and descriptor _relp below 
contain valid information) 
7 OD no valid descriptors exist in the definition 


unused 
is reserved for future use and must be "O"b 


this field contains a code indicating the section of the object 
segment to which value is relative. Codes are: 


O text section 
1 linkage section 
zZ symbol section 
> this symbol is a segment name 
4 static section 
is an offset (relative to the base of the definition section) to an 
aligned acc string representing the definition's symbolic name. 
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"be segname 
is an offset (relative to the base of the definition section) to the 
first class-—3 definition of this definition block. 


oS. n args 
- (obsolete) is the number of arguments expected by this external 
entry Point. This item is present only if argeount or 
has descriptors equals "1"b. This item is not defined in the system 
include file. 


9. descriptor. relp 
(obsolete) is an array of pointers (relative to the base of the text 
section) that point to the descriptors of the corresponding entry 
point arguments. This item is present only if has descriptors 
equals "i"b. This item is not defined in the system include file. 


The obsolete items are described here to illustrate earlier versions; 
translators should put these items in the entry sequence of the text section. 
See "Entry Sequence" above. 


In the case of a class-3 definition, the above structure is interpreted as 
follows: 


del 1 segname aligned, 

2 forward bit(18) unaligned, 
2 backward bit(18) unaligned, 
2 segname thread bit(18) unaligned, 
2 flags bit(15) unaligned, 
2 class bit(3) unaligned, 
2 symbol bit(18) unaligned, 
2 first _relp bit(18) unaligned; 

where: 

A forward 


is the same as above. 


2. backward 
is the same as above. 


4. segname thread 
is a thread (relative to the base of the definition section) to the 
next class-—-3 definition. The thread terminates when it points to a 
word that contains all O's. This thread provides a_ single 
sequential list of all class-—3 definitions in the object segment. 


4. flags 

is the same as above. 
Pi6 class 

is the same as above (and has a value of 3). 
Os symbol 


is the same as above. 


Ts first relp 
- is an offset (relative to the base of the definition section) to the 
first nonclass-—3 definition of the definition block. If the block 
contains no nonclass-3 definitions, it points to the first class-—3 
definition of the next block. If there is no next block, it points 
to a word that is all O's. 


The end of a definition block is determined by one of the following 
conditions (whichever comes first): 
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e forward points to an all zero word; 


e the current entry's class is not 3, and forward points to a class-3 
definition; 
® the current definition is class 3, and both forward and first _relp point 


to the same class-3 definition. 


The threading of definition entries is shown in Figure 1-1 above. The following 
paragraphs describe items in the unstructured portion of the definition section. 


Expression Word 


The expression word is the item pointed to by the expression pointer of an 
unsnapped link (see "Structure of the Linkage Section" below) and has the 
following format, defined in the system include file linkdcl.incl.pli: 


dcl 1 exp word aligned, 
2 type ptr bit(18) unaligned, 
2 exp fixed bin(17) unaligned; 
where: 


Lt type ptr 
is an offset (relative to the base of the definition section) to the 
link's type pair. 


Va exp 


is a signed value to be added to the offset (i.e., offset within a segment) 
of the resolved link. 


Type Pair 


The type pair defines the external symbol pointed to by a link and has the 
following format, defined in the system include file linkdcl.incl.pl1: 


del 1 type pair aligned, 
2 type bit(18) unaligned, 
2 trap ptr bit(18) unaligned, 
2 seg ptr bit(18) unaligned, 
2 ext ptr bit(18) unaligned; 
where: 
1 type 


assumes a value from 1 to 6: 


is a self-referencing link (i.e., the segment in which the external 
symbol is located is the object segment containing this link or a dynamic 
related section of the link) of the form: 


myself ;O+expression,modifier 


unused; it was earlier used to define a now obsolete ITP-type link. 
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2. 


ce 


4, 
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is a link referencing a specified reference name but no symbolic 
offset name, of the form: 


refname;0+expression modifier 


rT] 
is a link referencing both a symbolic reference name and a symbolic 
offset name, of the form: 

refname} offsetname+expression,modifier 

5 
is a self-referencing link having a symbolic offset name, of the 
form: 

myself|offsetname+ex pression ,modifier 
(obsolete) same as type 4 except that the external item is created 
if it is not found. 
trap ptr 
~ ais an offset (relative to the base of the definition section) to 
either an initialization structure (if type equals 5 and seg ptr 
equals 5, or if type equals 6) or to a trap word. see 
seg ptr 

= is a code or a pointer depending on the value of type. For types 1 
and 5, this item is a code that can assume one of the following 
values, designating the sections of the self-referencing object segment: 

0 
is a self-reference to the object's text section; such a reference 
is represented symbolically as "*text"., 

1 
is a self-reference to the object's linkage section; such a reference 
is represented symbolically as "*link". 

2 ; 
is a self-reference to the object's symbol section; such a reference 
is represented symbolically as "*symbol". 

4 
is a self-reference to the object's static section; such a reference 
is represented symbolically as "*static". 

5 
is a reference to an external variable managed by the linker; such a 
reference is represented symbolically as "*system". 
For types 3, 4, and 6, this item is an offset (relative to the base 
of the definition section) to an aligned acc string containing the 
reference name portion of an external reference. (See the MPM Reference 
Guide.) 

ext ptr 


has a meaning depending on the value of type. For types 1 and 3, 
this value is ignored and must be zero. For types 4, 5, and 6, this 
item is an offset (relative to the base of the definition section) 
to an aligned acc string containing the entry point name of an external 
reference. If type equals 5 and seg ptr equals 5, the ace string 
contains the name of the external variable. (See the MPM Reference 
Guide for a discussion of entry point names.) 
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Trap Word 


The trap word is a structure that specifies a trap procedure to be called 
before the link associated with the trap word is resolved by the dynamic linking 
mechanism. It consists of relative pointers to two links. (Links are defined 
under "Structure of the Linkage Section" below.) The first link defines the 
entry point in the trap procedure to be called. The second link defines a block 

% of information that is passed as one of the arguments of the trap procedure. 
The trap word has the following format, defined in the system include file 
linkdel.inel.pl1: 


del 1 trap word aligned, 
2 call ptr bit(18) unaligned, 
2 arg ptr bit(18) unaligned; 
where: 


1. call ptr 
is an offset (relative to the base of the linkage section) to a link 
defining the entry point of the trap procedure. 


2. arg ptr 
: is an offset (relative to the base of the linkage section) to a link 
defining information of interest to the trap procedure. 


Initialization Structure for Type 5 system and Type 6 Links 


a ee 


This structure specifies how a link target first referenced because of a 
type 5 *system or a type 6 link should be initialized. It has the following 
format: 


del 1 initialization info aligned, 
2n words i fixed bin, 
2 code fixed bin, 
2 info (n_words) bit(36) aligned; 


where: 
1. n words 
= is the number of words required by the new variable. 
2. code 
indicates what type of initialization is to be performed. It can 
have one of the following values: 
0 : 
no initialization is to be performed 
3 2 
copy the info array into the newly defined variable 
4 
initialize the variable as an area 
3. info 


is the image to be copied into the new variable. It exists only if 
eode is 3. 
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n_entries 
defp 
defp 


defp 


definition name 


defp 
hash table 


defp 
defp 


n_entries 


defp block_hdrp 


ae oe ee ee ag component name 


block_hdrp 
hash table 


n_dup_names 


a Se el block_hdrp duplicate name table 


dafn black hdro 
Uvip bie ed 


WIVEN 


block harp 


block _hdrp 
block harp 


duplicate name table 


Figure 1-2. Definition Hash Table 
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Definition Hash Table 


A definition hash table may be present in the definition section of an 
object segment. In its basic form, the definition hash table contains an array 
of pointers to definitions. The definition hashing algorithm selects a 
particular pointer. If the selected pointer does not point to the desired 
definition, a linear search is then performed until the appropriate definition 
is found or a zero pointer is encountered. The initial hash code is generated 
by taking the remainder of the first word of the definition name (the count and 
first three characters of the "acc" format string) divided by the size of the 
hash table. The hash table size is such that it is never more than 80% full. 


In bound segments, different components may contain definitions with 
identical names. In this case, a second hash table is required in order to 
resolve ambiguities. In addition to this second hash table, a duplicate name 
table must be provided for each duplicated definition name. 


The format of the tables described above is shown in Figure i-2 and is 
described below: 


The definition name hash table is pointed to oy a relative pointer in the 
definition section header. It must contain one nonzero entry for’ each 
non-class-3 definition name. 


del 1 defht aligned, 
é n_entries fixed bin, 
2 table (n refer (defht.n_entries)), 


(3 defp bit(18), 
3 unused bit(18)) unal; 


where: 
1. n_entries 

is the number of elements in the hash table. 
2s defp 


is an array of pointers to non-class-3 definitions. In the case of 
a duplicated definition name, a particular defp does not point 
directly to a definition, but rather to a duplicate name table (see 
below). 


A component name hash table is present only if duplicated definition names 
are present in a bound segment. It must immediately follow the definition hash 
table. There is one entry in this hash table for each bound segment component 
name and synonym (i.e., for each class-3 definition). 


del 1 compht aligned, 
2 n_entries fixed bin, 
2 table (nrefer (compht.n_entries)), 
(3 defp bitc 1), 
3 block_hdrp bit(18)) unaligned; 
where: 
1. n_entries 


is the number of elements in the component name hash table. 


2. table 
contains one nonzero element for each class-3 definition. 
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3. defp 
is a relative pointer to a class-3 definition. 


AY block_hdrp 
is a relative pointer to the first class-3 definition of the 
definition block containing the definition pointed to by defp. 


A duplicate name table must be supplied for each duplicated definition 
name. Each table has one entry for each instance of the duplicated name. The 
definition searching algorithm can determine whether the relative pointer 
retrieved from the definition hash table points to a definition or to a 
duplicate name table by examining the left half of the first word pointed to. A 
definition never contains a zero forward thread, while a duplicate name table is 
never nonzero in the left half of the first word. 


del 1 dupt aligned, 
2 n_dup_names fixed bin, 
2 table (n refer (dupt.n_dup_names)), 
(3 defp bit(18), 
3 block_hdrp bit(18)) unaligned; 
where: 


bes n_dup_names 
is the number of instances of a given duplicated name. 


2. table 
contains one element for each instance of the duplicated name. 


oe defp 
is a pointer to a non-class-3 definition. 


4, block_hdrp 


is a pointer to the first class-3 definition of the definition block 
containing the non-class-3 definition. 


Definition searching with a definition hash table is done by first 
searching for the definition name. If no duplicate name table is encountered, 
no ambiguity exists and the correct definition is quickly found. If a duplicate 
name table is .encountered, the component name hash table must be searched. 
Then, a linear search is done on the duplicate name table to match a block hdrp 
with the block hdrp in the component name hash table. 


STRUCTURE OF THE STATIC SECTION 


The static section is unstructured. 


STRUCTURE OF THE LINKAGE SECTION 


The linkage section is subdivided into four distinct components: 


1. A fixed-length header that always resides at the base of the linkage 
section 


2. A variable length area used for internal (static) storage (optional) 
3% A variable length structure of links (optional) 


4, First-reference trap (optional) 
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These four components are located within the linkage section in the following 
sequence: 


header 

internal storage (if present) 
links (if present) 

trap (if present) 


The length of the linkage section must be an even number of words and must 
start on an even-word boundary; in addition, the link substructure must also 
begin at an even location (offset) within the linkage section. 


When an object segment is first referenced in a process, its linkage section 
is copied into a per-process data base. At this time certain items in the copy 
of the header are initialized. Items not explicitly described as being initialized 
by the linker are set by the program that generates the object segment. In 
addition, the first two words of the header are filled in by the linker (when 
the header is copied) with a pointer to the beginning of the object segment's 
definition section. For more information see the MPM Reference Guide and "Standard 
Stack and Linkage Area Formats" in Section 2 of this manual. 


Linkage Section Header 


The header of the linkage section (in an object segment) has the following 
format, defined in the system include file object link dels.incl.pl1: 


del 1 virgin linkage header aligned based, 

2 pad a bit(30) unal, 
2 defs in link bit(6) unal, 
2 def offset fixed bin(18) uns unal, 
2 first ref relp fixed bin(1&) uns unal, 
2 filled in later bit( 144), 
2 link begin fixed bin(18) uns unal, 
2 linkage section lng fixed bin(18) uns unal, 
2 segno pad ~ fixed bin(18) uns unal, 
2 static length fixed bin(18) uns unal; 

where: 

j pad 


is reserved for future use and must be 0. 


2. defs in link 
~ Indicates whether or not there are definitions in the linkage section. 
If there are definitions in the linkage section, the value contained 
here is "010000"b. 


3. def offset 
a is an offset (relative to the base of the object segment) to the 
base of the definition section. 


J 4. first ref relp 

~ is an offset (relative to the base of the linkage section) to the 
first-reference trap. This trap is activated by the linker when the 
first reference to this object segment is made within a given process. 
If the value of this item is 0, there is no first-reference trap. 
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5. filled in later 

“is initialized by the linker when the header is copied. As a result 
of initialization by the linker, the first word becomes a pointer to 
the object segment's symbol section. It is used by the linker to 
snap links relative to the symbol section. The second word becomes 
a pointer to the original linkage section within the object segment. 
It is used by the link unsnapping mechanism. The last two words 
remain unused. 


6. link begin 
~ ds an offset (relative to the base of the linkage section) to the 
first link (the base of the link array). 


ee linkage section lng 
is the entire length in words of the entire linkage section. 


8. segno pad 
~ is the segment number of the object segment. It is initialized by 
the linker when the header is copied. 


9. static length 
“is the length in words of the static section and is valid even when 
static is part of the linkage section. It is initialized by the 
linker if not filled in by the translator. 


Internal Storage Area 


The internal storage area is an array of words used by translators to 
allocate internal static variables and has no predetermined structure. 


Links 


A linkage section may contain an array of link pairs each of which defines 
an external name, referenced by this object segment, whose effective address is 
unknown at compile time. References to external entities are made by indirect 
references through a link, which has been copied from the pure linkage section 
of an object segment. to the combined linkage section in the process directory. 
A link initially contains a fault tag 2 modification instead of an ITS modification. 
When the indirect reference is attempted, the fault occurs and is intercepted by 
the dynamic linking mechanism. Additional information in the link is used to 
locate the item referenced and, if successful, the link is replaced by an ITS 
pointer to the item. Figure i-2 iliustrates the structure of a link. 


A link must. reside on an even location in memory, and must therefore be 
located at an even offset from the base of the linkage section. A link has the 
following format, defined in the system include file object link dels.incl.pl1: 


del 1 object link aligned based, 
2 header relp fixed bin(17) unal, 
2 ringno fixed bin(3) uns unal, 
2 mbz bit(3) unal, 
2 run depth fixed bin(5) unal, 
2 tag bit(6) unal, 
2 expression relp fixed bin(1&) uns unal, 
2 mbz2 7 bit(12) unal, 
2 modifier bit(6) unal; 
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where: 


J i. header relp 
, ~is an offset (relative to the link itself) to the head of the linkage 
section. It is, in other words, the negative value of the link 
pair's offset within the linkage section. 


2. ringno 
is the ring number of the ITS pointer. 


2. mbz 
is reserved for future use and must be "O"b. 


4. run depth 

. > must be 0 in a generated (unsnapped) link. When the link is snapped, 
this field is filled in with the number of the current run unit 
level. 


J 5. tag 
is a constant (46)8 that represents the hardware fault tag 2 and 
distinctly identifies an unsnapped link. The snapped link (ITS pair) 
has a distinct (43)8 tag. See the MPM Reference Guide. 


J 6. expression relp 
is an offset (relative to the base of the definition section) to the 
expression word for this link. 


7. mbz2 
is reserved for future use and must be "QO"b. 


8. modifier 
is a hardware address modifier. When the link is snapped, this 
becomes the modifier of the ITS pair. 


First-Reference Trap 


It is sometimes necessary to perform certain types of initialization of an 
object segment when it is first referenced for execution (i.e., linked to) in a 
given process--for example, to store some per-process information in the segment 
before it is used. fThe first-reference trap mechanism provides this facility 

% for use by various mechanisms, the status code assignment mechanism being an 
example. 


A first-reference trap consists of two relative pointers. The first points 
to a link defining the first reference procedure entry point to be invoked. The 
second points to a link defining a block of information to be passed as an 
argument to the first-reference procedure. For more details on first-reference 

| traps, see the MPM Reference Guide. The first reference trap has the following 
format, defined in the system include file object link dels.inel.pli: 


del 1 fr traps aligned based, 
2 decl vers fixed bin, 
2n traps fixed bin, 
2 trap array (n fr_traps refer(fr _traps.n traps)) aligned, 
3 call relp fixed bin(18) uns unal, ~ 
3 info relp fixed bin(18) uns unal, 
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where: 


1. 


decl vers 
is the version number of the structure. 


n traps 
specifies the number of traps. 


trap array 
is an array of information about each first-reference procedure. 


call _relp 
is an offset (relative to the base of the linkage section) to a link 
defining a procedure to be invoked by the linker upon first 
reference to this object within a given process. 


into. relp 
~ is an offset (relative to the base of the linkage section) to a link 
specifying a block of information to be passed as an argument to the 
first. reference ‘procedure; if info relp is 0, there is no such 
block. 
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STRUCTURE OF THE SYMBOL SECTION 


ee 


The symbol section consists of one or more symbol headers threaded together 
to form a single list. A symbol header has two main functions: to document the 
circumstances under which the object segment was created, and to serve as a 
repository for information (relocation information, compiler's symbol tree, 
etc.) that does not belong in any of the other sections. 


The symbol section must contain at least one symbol header, describing the 
circumstances under which the object segment was created. A symbol section can 
contain more than one symbol header. An example of multiple symbol headers is 
the case of a bound segment where in addition to the symbol header describing 
the segment's creation by the binder, there is also a symbol header for each of 
the component object segments. 


Each symbol header can point to a free-format area. The free-format area 
can contain any information whatsoever, and the object segment will execute 
properly. However, the Multics debugging utilities (e.g., probe) place 
stringent requirements on the format of the free area, and these are followed by 
the translators for PL/I, FORTRAN, and COBOL. See Appendix 8B for additional 
information on the contents of the free-format area used by those three 
languages. 


Symbol Block Header 


All symbol blocks have a_ standard fixed-format block, although not all 
items in the block have meaning for all symbol blocks. The description of a 
particular symbol block lists items that have meaning for that symbol block. 
The block has the following format, defined by the system include file 
std_symbol_block.incl.p11: 


del 1 std_symbol_block based aligned, 

2 decl version fixed bin initial(1), 
2 identifier char(8) aligned, 
2 gen_number fixed bin, 
2 gen_created fixed bin(71), 
2 object_created fixed bin(71), 
2 generator char(8), 
2 gen_version unaligned, 

3 offset bit (18), 

3 size bit(18), 
2 userid unaligned, 

3 offset bit(18), 

3 size bit(18), 
2 comment unaligned, 

3 offset bit(18), 

3 size bit(18), 
2 text_boundary bit(18) unaligned, 
2 stat_boundary bit(18) unaligned, 
2 source_map bit(18) unaligned, 
2 area_pointer bit(18) unaligned, 
2 backpointer bit(18) unaligned, 
2 block_size bit(18) unaligned, 
2 next_block bit(18) unaligned, 
2 rel_text bit(18) unaligned, 
2 rel def bit(18) unaligned, 
2 rel_link bit(18) unaligned, 
2 rel_symbol bit(18) unaligned, 
2 mini_truncate bit(18) unaligned, 
2 maxi_truncate bit(18) unaligned; 
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12. 


13. 
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decl version 
~ is the version number of the structure. 
identifier 
is a symbolic name identifying the type of symbol block. 


gen_number 
is a code designating the version of the generator that created this 
object segment. A  generator's version number is normally changed 
when the generator or its output is significantly modified. 


gen_created 
is a calendar clock reading specifying the date and time when this 
generator was created. 


object_created 
is a calendar clock reading specifying the date and time when this 
symbol block was generated. 


generator 
is the name of the program that generated this symbol block. 


offset 
is an offset (relative to the base of the symbol block) to an 
aligned string describing the version of the generator. For 
example: 


"PL/I Compiler Version 7.3 
of Wednesday, July 28, 1971" 


The integer part of the version number embedded in the string must 
be identical to the number stored in gen_number. 


size 
is the length of the aligned string describing the version of the 
generator. 
userid 
is the name of the user for whom this symbol block was created. 
offset 
is an offset (relative to the base of the symbol block) to an 
aligned string containing the access identification (i-e., the value 
returned by the get_group_id subroutine described in the MPM 
Subroutines) of the user for whom this symbol block was created. 
size 
is the length of the aligned string containing th access 
identification of the user for whom the symbol block was created. 
comment 
an aligned string containing generator-dependent symbolic 
information. For example, a compiler might store diagnostic 
messages concerning nonfatal errors encountered while Belenatsue the 
object segment. 
offset 
is an offset (relative to the base of the symbol block) to the 
comment. A value of "O"b indicates no comment. 
size 


is the length of the aligned string containing generator-dependent 
symbolic information. 
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Source Map 


The source map is a structure that uniquely identifies the source segments 
used to generate the object segment. It has the following format, defined in 
the system include file source map.incl.pl1: 


del 1 source map aligned based, 
2 version fixed bin initial(1), 
2 number fixed bin, 
2 map (n refer (source _map.number)) aligned, 
3 pathname unaligned, 
4 offset bit(18), 
4 size bit (1s), 


7/81 1-22. 1 AK92C 


THIS PAGE INTENTIONALLY LEFT BLANK 


7/81 AK92C 


15. 


16. 


18. 


19. 


20. 


Zi. 


22. 


23. 


24. 


25. 


26. 


27. 
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text boundary 
is a number indicating the boundary on which the text section must 
begin. For example, a value of 32 would indicate that the text 
section must begin on a 0 mod 32 word boundary. This value must be 
a multiple of 2. It is used by the binder to determine where to 
locate the text section of this object segment. , 


stat _boundary 
is the same as text boundary except that it applies to the internal 
static area of the linkage section of this object segment. 


source map 
is an offset (relative to the base of the symbol block) to the 
source map (see "Source Map" below). 


area_pointer 
is anoffset (relative to the base of the symbol block) to the 
free-format area of the symbol block. The contents of this area 
depend upon the symbol block. If the symbol block was created by a 
translator, this area may contain a runtime symbol table and/or a 
statement map. If the symbol block was created by the binder, this 
area contains the bind map. 


backpointer 
is an offset (relative to base of the symbol block) to the base of 
the symbol section; that is, the negative of the offset of the 
symbol block in the symbol section. 


block size 
is the size of the symbol block (including the block) in words. 


next_block 
is a thread (relative to the base of the symbol section) to the next 
symbol block. This item is "O"b for the last block. 


rel_text 
is an offset (relative to the base of the symbol block) to text 
section relocation information (see "Relocation Information" below). 


bel der 
is an offset (relative to the base of the symbol block) to 
definition section relocation information. 


Pele 1k 
is an offset (relative to the base of the symbol block) to linkage 
section reiocation informavivi. 


rel symbol 
is an offset (relative to the base of the symbol block) to symbol 
section relocation information. 


mini truncate 
~ is an offset (relative to the base of the symbol block) starting 
from which the binder systematically truncates control information 
(such as relocation bits) from the symbol section, while still 
maintaining such information as the symbol tree. 


maxi truncate 
~ is an offset (relative to this base of the symbol block) starting 
from which the binder can optionally truncate nonessential parts of 
the symbol tree in order to achieve maximum reduction in the size of 
a bound object segment. 
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3 uid bit(36) aligned, 


3 dtm fixed bin(71); 
where: 
1. version 

is the version number of the structure. 
2. number 


is the number of entries in the map array; that is, the numbder of 
source segments used to generate this object segment. 


3. pathname 
an aligned string containing the absolute pathname of this source 
segment. 


4, offset 
is an offset (relative to the base of the symbol block) to the 
pathname. 


pe size 
is the length of the pathname. 


6. uid 
is the unique identifier of this source segment at the time the 
object segment was generated. 


7. dtm 
is the date-time-modified value of this source segment at the time 
the object segment was created. 


Relocation Information 


Relocation information, designating all instances.of relative addressing 
within a given section of the object segment, enables the relocation of the 
section (as in the case of binding). A variable-length prefix coding scheme is 
used, where there is a logical relocation item for each halfword of a given 
section. If the halfword is an absolute value (nonrelocatable), that item is a 
Single bit whose value is 0. Otherwise, the item is a string of either 5 or 15 
bits whose first bit is set to "1"b. The relocation information is concatenated 
to form a single string that can only be accessed sequentially. If the next bit 
is a zero, it is a single-bit absolute relocation item; otherwise, it is either 
a 5~ or a 15-bit item depending upon the relocation codes defined below. 


Tnere are four distinct blocks of relocation information, one for each of 
the four object segment sections: text, definition, linkage and symbol; these 
relocation blocks are known as rel _text, rel_def, rel_link and _ rel_symbol, 
respectively. 7 


The relocation blocks reside within the symbol block of the generator that 
produced the object segment. The correspondence between the packed relocation 
items and the halfwords ina given section is determined by matching the 
sequence of items with a sequence of halfwords, from left-to-right and from 
word-to-word by increasing value of address. 


The relocation block pointed to from the symbol block header (e.g., 
text_relocation relp) is structured as follows: 


del 1 relinfo aligned, 
2 decl_ vers fixed bin initial(2), 
2 n_bits fixed bin, 
2 relbits bit(O refer(relinfo.n_bits)) aligned; 
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where: 


Te deel vers 
is the version number of the structure. 


2. n bits 
is the length (in bits) of the string of relocation bits. 


3. relbits 
is the string of relocation bits. 


Following is a tabulation of the possible codes and their corresponding 
relocation types, followed by a description of each relocation type. 
Translators indicate the relocation code in the assembly-like listing of an 
object segment by a character. The second column below indicates the character 
used by standard translators. The third column indicates the character used by 
the ALM assembler. 


"O"D - aa - absolute 

"10000"b - t O - text 

"10001"b - 1 7 = negative text 
"10010"b - 2 2 - link 18 

"10011"b - 3 3 - negative link 18 
"10100"b - 1 4 - link 15 

TOTO LD e- id? (Be = definition 

"70.1106 - s 6 = symbol 

101 1-1"%b - 7 Ff - negative symbol 
"11000"b - 8 8 - internal storage 18 
"11001"b - i 9 - internal storage 15 
PLO TOD - r Lb _—- self relative 
104-15 - unused 

™71100"b - unused 

"71101"b - unused 

Pil Lo" b - expanded absolute 
"U0 711"D - e # escape 


where: 


1. absolute 
does not relocate. 


2e text 
uses text section relocation counter. 


3. negative text 
uses text section relocation counter. The reason for having 
distinct relocation codes for negative quantities is that special 
coding might be necessary to convert the 18-bit field in question 
into its correct fixed binary form. 


4, link 18 
uses linkage section relocation counter on the entire 18-bit 
halfword. This, as well as the negative link 18 and the link 15 
relocation codes apply only to the array of links in the linkage 
section (i.e., by definition, usage of these relocation codes 
implies external reference through a link). 
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negative link 18 
is the same as link 1 


oe) 
ey) 
oO 
12) 
< 
fo) 


link 15 
uses linkage section relocation counter on the low-order 15 bits of 
the halfword. This relocation code can only be used in conjunction 
with an instruction featuring a base/offset address field. 


definition 


indicates that the halfword contains an address that is relative to 
the base of the definition section. 
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8. symbol 
uses symbol section relocation counter. 


9. negative symbol 
is the same as symbol above. 


10. internal storage 18 
uses internal storage relocation counter on the entire 18-bit 


halfword. 


13 internal storage 15 
uses internal storage relocation counter on the low-order 15 bits of 
the halfword. 


j2. self relative 
indicates that the halfword contains a relocatable address that is 
referenced using a location counter modifier; the instruction is 
self-relocating. 


13. expanded absolute 

allows the definition of a block of absolute relocated halfwords, 
for efficiency reasons. It has been established that a major part 
of an object program has the absolute relocation code. The five 
bits of relocation code are immediately followed by a fixed length. 
10-bit field that is a count of the number of contiguous halfwords 
all having an absolute relocation. Use of the expanded absolute 
code can be economically justified only if the number of contiguous 
absolute halfwords exceeds 15. 


14. escape 
reserved for possible future use. 


STRUCTURE OF THE OBJECT MAP 


The object map contains information used to locate the various sections of 
an object segment. The map itself can be located immediately before or 
immediately after any one of the five sections. Translators normally place it 
immediately after the symbol section. The last word of the object segment (as 
defined by the bit count of the object segment) must contain a left-justified 
18-bit offset (relative to the base of the object segment) to the object map. 
The object map has the following format, defined in the system include file, 
object_map.incl.pl1: 


del 1 object_map aligned, 
2 decl_ vers fixed bin init(2), 
2 identifier char(8) aligned, 
2 text offset bit(18) unaligned, 
2 text length bit(18) unaligned, 
2 definition_offset bit(18) unaligned, 
2 definition length bit(18) unaligned, 
2 linkage offset bit(18) unaligned, 
2 linkage length bit(i8) unaligned, 
2 static offset bit(18) unaligned, 
2 static length bit(18) unaligned, 
2 symbol offset bit(18) unaligned, 
2 symbol length bit(18) unaligned, 
2 break_map_ offset bit(18) unaligned, 
2 break _map_length bit(18) unaligned, 
2 entry bound bit(18) unaligned, 
2 text_link offset bit(18) unaligned, 
2 format aligned, 
3 bound bit(1) unaligned, 
3 relocatable bit(1) unaligned, 
3 procedure bit(1) unaligned, 
3 standard bit(1) unaligned, 
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18. relocatable 
indicates if the object segment is relocatable; that is, if it 
contains relocation information. This information (if present) must 
be stored in the segment's first symbol block. See "Structure of 
the Symbol Section" above. 
MED the object segment is relocatable 
OND the object segment is not relocatable 


19. procedure 
indicates whether this is an executable object segment. 
aie! La 6) this is an executable object segment 
WOM this is not an executable object segment 


20. standard 
indicates whether the object segment is in standard format. 
ms ld 8 the object segment is in standard format. 
OD the objeet segment is not in standard format 


21. separate static 
indicates whether the static section is separate from the linkage 
section. 
VAS the static section is separate from the linkage section 
OND the static section is not separate from the linkage section 


22. links in_text 
indicates whether the object segment contains text-embedded links. 
Rae the object segment contains text-embedded links 
Oak the object segment does not contain text-embedded links 


23. perprocess static 
indicates whether the static section should be reinitialized for a 
run unit. 
ED static section is used as is 
"O"D static section is per run unit 


24. unused 
is reserved for future use and must be "0"b, 


GENERATED CODE CONVENTIONS 


The following discussion specifies those portions of generated code that 
must conform to a system-wide standard. For a description of the various 
relocation codes see "Structure of the Symbol Section" above. 


Text Section 


Those parts of the text section that must conform to a system-wide standard 
are: 
entry sequence 
text relocation codes. 


ENTRY SEQUENCE 


The entry sequence must fulfill two requirements: 


hs The location preceding the entry point (i.e., entry point minus 1) 
must contain a left adjusted 18-bit relative pointer to the definition 
of that entry point within the definition section 
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es The entry sequence executed within that entry point must store an ITS 
pointer to that entry point in the entry ptr field in the stack frame 
header (as described in the Stack frame include file). The 
procedure's current stack frame can then be used to determine the 
address of the entry point at which it was invoked. That entry's 
symbolic name can be reconstructed through use of its definition 
pointer. (See "Entry Sequence" earlier in this section.) 


TEXT RELOCATION CODES 


The following list defines those relocation codes that can be generated in 
conjunction with the text section. These can be generated only within the scope 
of the restrictions specified. 


absolute no restriction 

text — no restriction 

negative text no restriction 

link 18 can only be a direct (i.e., unindexed) reference to 
a link. 

link 15 can only appear within the address field of a 
pointer-register/offset type instruction 
(bit 29 = "1"b). The first two bits of the modifier 


field of the instruction cannot be "10"b. If the 
instruction uses indexing, the first two bits of the 
modifier must be "11"b. Also the following 
instruction codes cannot have this relocation code: 


STBA (551)8 
STBQ (552)8 
STCA (751)8 
STCQ (752)8 


definition the offset to be relocated must be that of the 
beginning of a definition (relative to the beginning 
of the definition section). 


symbol no restriction 
internal storage 18 no restriction 


internal storage 15 can only apply to the left half of a word. If the 
word is an instruction, the first two bits of the. 
modifier must not be "10"b., 


self relative no restriction 


expanded absolute no restriction 


The restrictions imposed upon the link 15 and internal storage 15 
relocation codes stem from the fact that these relocation codes apply to 
pointer-register/offset type address fields encountered in the address portion 
of machine instructions. Since the effective value of such an address is 
computed by the hardware at execution time, certain hardware restrictions are 
imposed on instructions containing them. When the Multics binder processes 
these instructions, it often resolves them into simple-address format and has to 
further modify information in the opcode (right-hand) portion of the instruction 
word. Therefore, these relocation codes must only be specified in a context 
that is comprehensible to the Multics processor. 
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Definition Section 
Those parts of the definition section that must conform to a system-wide 
standard are: 
general structure 


definition relocation codes 
implicit definitions 


DEFINITION RELOCATION CODES 


absolute . no restriction 
text no restriction 
link 18 no restriction 
definition no restriction 
symbol no restriction 
internal storage 18 no restriction 
self relative no restriction 
expanded absolute no restriction 


IMPLICIT DEFINITIONS 


All generated object segments must feature the following implicit 
definition: 
symbol _ table defines the base of the symbol block generated by the 
r tiv t f 


current language processor, 
symbol section. 


Linkage Section 
Those parts of the linkage section that must conform to a system-wide 
Standard are: 
internal storage 


links 
linkage relocation codes 


INTERNAL STORAGE 


The internal storage is a repository for items of the internal static 
storage class. It may contain data items only; it cannot contain any executable 
code. 
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LINKS 


The link area can only contain a set of links. The links must be 
considered as distinct unrelated items, and no structure (e.g., array) of links 
can be assumed. They must be accessed explicitly and individually through an 


unindexed internal reference featuring the link 18 or the link 15 relocation 
codes. The order of links will not necessarily be preserved by the binder. 


LINKAGE RELOCATION CODES 


Only the linkage section header and the links can have relocation codes 
associated with them (the internal storage area has associated with it a single 
expanded absolute relocation item). They are: 


absolute no restriction; mandatory for the internal storage 
area - 

text no restriction 

link 18 no restriction 

negative link 18 no restriction 

definition no restriction 

internal storage 18 no restriction 

expanded absolute no restriction 


Static Section 


The static section does not have relocation codes associated with it. 
Absolute relocation is assumed. See "Internal Storage Area" above. 


Symbol Section 


The symbol section can contain information related to some other section 
(such as a symbol tree defining addresses of symbolic items), and therefore can 
have relocation codes associated with it. They are: 


absolute no restriction 
text no restriction 
link 18 no restriction 
definition no restriction 
symbol no restriction 
negative symbol no restriction 
internal storage 18 no restriction 
self relative no restriction 
expanded absolute no restriction 
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STRUCTURE OF BOUND SEGMENTS 


A bound segment consists of several object segments that have been combined 
so that all internal intersegment references are automatically prelinked and to 
reduce the combined size by minimizing page breakage. The component segments 
are not simply concatenated; the binder breaks them apart and creates an object 
segment with single text, definition, static, linkage, and symbol sections as 
illustrated in Figure 1-3 below. (When the static section is separate, it is 
located before the linkage header rather than between the linkage header and the 
links.) As explained below, the definition section and link array are 
completely reconstructed while the text, internal static, and symbol sections 
are the corresponding concatenations of the component segments' text, internal 


Static, and symbol sections with relocation adjustments. (See "Structure of 
the Symbol Section" above.) If all of the components! static sections are 
separate (i.e., not in linkage), the bound segment has a separate static 
section; otherwise, all component static sections are placed in the bound 


segment's linkage section. 
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Figure 1-4. Structure of a Bound Segment 
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Internal Link Resolution 


The primary distinction between bound and unbound groups of segments occurs 
in the manner in which they reference external items and are themseives 
referenced. Most references by one component to another component in the same 
bound segment are prelinked; i.e., the link references are converted to direct 
text-to-text references and the associated links are not regenerated. The 
remaining external links are combined so that for the whole bound segment there 
is only one link for each different target. Prelinking enables some component 
segments to lose their identity in cases where the bound segment itself is the. 
main logical entity, having been coded as separate segments for ease of coding 
and debugging. Definitions for external entries that are no longer necessary, 
i.e., have become completely internal, can be omitted from the bound segment 
(see the bind command described in MPM Commands). 


Definition Section 


The definition section of a bound segment is generally more elaborate than 
that of an unbound object segment because it reflects both the combination and 
deletion of definitions. There is a definition block for each component. It 
contains the retained definitions and the segment names associated with the 
component. This organization allows definitions for multiple entries with the 
same name to be distinguished. The first definition block is for the binder and 
contains a definition for bind _map, discussed below. 


Binder Symbol Block 


The symbol block of the binder has a standard header if all of the 
components are standard object segments. The symbol block can be located using 
the bind map definition. Most of the items in the header are adequately 
explained under "Structure of the Symbol Section" above; however, some have 
special meaning for bound segments. The format of a standard symbol block 
header is repeated below for reference, followed by the explanations specific to 
the binder's symbol block. 


del 1 std symbol header based aligned, 

2 decI_ version fixed bin initial(1), 
2 identifier char(8) aligned, 
2 gen_number fixed bin, 
2 gen created fixed bin(71), 
2 object_created fixed bin(71), 
2 generator char(8), 
2 gen_version unaligned, 

3 offset bit(18), 

3 size bit(18), 
2 userid unaligned, 

3 offset bit(18), 

3 size bit(18), 
2 comment unaligned, 

3 offset bit(18), 

3 size bit(18), 
2 text_boundary bit(18) unaligned, 
2 stat_boundary bit(18) unaligned, 
2 source map bit(18) unaligned, 
2 area_pointer bit(18) unaligned, 
2 backpointer bit(18) unaligned, 
2 block size bit(18) unaligned, 
2 next_block bit(18) unaligned, 
2 rel _ text bit(18) unaligned, 
2 rel def ~ bit(18) unaligned, 
2 rel link bit(18) unaligned, 
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where: 


2 rel symbol 
2 mini truncate 
2 maxi truncate 


2. identifier 


is the string "bind map". 


6. generator 


is the string "binder". 


13. comment 


is always "O"b. 


19. area pointer 


Bound segments currently are not relocatable, 


Bind Map 


is an offset 


(relative to 
beginning of the bind map. 


bit(1@) unaligned, 
bit(1&) unaligned, 
bit(18) unaligned; 


the base of the symbol block) 


(See "Bind Map" below.) 


to the 


so none of the relocation 
relative pointers or truncation offsets have any meaning. 


The bind map is part of the symbol block produced by the binder and describes 
the relocation values assigned to the various sections of the bound component 


object segments. 


It consists of a variable length structure followed by an area 


in which variable length symbolic information is stored. The bind map structure 


has the following format, defined in the system include file bind map.incl.pl1: 


del 1 bindmap based 


where: 


2 del version 
2 n components 


2 component(0 refer(bindmap.n components) ) 


3 name 

4 name ptr 
4 name lng 
comp name 
text start 
text lng 
stat start 
stat lng 
symb start 
symb lng 
defblock ptr 
n blocks 


WOWWWWWWW WWW 
ne 
3 
AY) 
3 
fa) 


Df name ptr 
3 bf name lng 

2 bf date up 

2 bf date mod 


1. del version 
is a constant designating the format of this structure; this constant 
is modified whenever the structure is, allowing system tools to easily 
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differentiate bind map formats. 
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aligned, 


fixed bin, 
fixed bin, 


aligned, 


bit( 18) 
bit(18) 
char(8) 
bit( 18) 
bit(18) 
bit(1&) 
bit(18) 
bit (18) 
bit (18) 
bit(18) 
bit(18) 


aligned, 


bit(18) 
bit(1&) 


unaligned, 
unaligned, 
aligned, 

unaligned, 
unaligned, 
unaligned, 
unaligned, 
unaligned, 
unaligned, 
unaligned, 
unaligned, 


unaligned, 
unaligned, 


char(24), 
char(24); 


This structure is version one (1). 
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10. 


ke 


(ee 


Ss 


14. 


15 


16. 


ee 


18. 


19. 


n_components 
is the number of component object segments bound within this bound 
segment. 


component 
is a variable-length array featuring one entry per bound component 
object segment. 


name 
is the symbolic name of the bound component. This is the name under 
which the component object was identified within the archive file 
used as the binder's input (i.e., the name corresponding to the 
object's objectname entry in the bindfile). 
name ptr 
is the offset (relative to the base of the binder's symbol block). 
name_lng 


is the length (in characters) of the component's name. 


comp name 
is the name of the translator that created this component object 
segment. 


text start 
is the offset (relative to the base of the bound segment) of the 
component's text section. 


text ling 
is the length (in words) of the component's text section. 


stat start 
is the offset (relative to the base of the static section) of the 
component's internal static. 


stat_ling 
is the length of the component's internal static. 


symb_start 
is an offset (relative to the base of the symbol section) to the 
component's symbol section. 


symb_ing 
is the length of the component's symbol section. 


defblock ptr 
if nonzero, this is a pointer (relative to the base of the 
definition section) to the component's definition block (first 
class-3 segname definition of that component's definition block). 


n_blocks 
is the number of symbol blocks in the component's symbol section. 


bf_name_ptr 
is the offset (relative to the base of the binder's symbol block) of 
the symbolic name of the bindfile. 


bf name ling 
is the length (in characters) of the bindfile name. 


bf _date_up 
is the date, in symbolic form, that the bindfile was updated in the 
archive (of object segments) used as input by the binder. 


bf_date mod 


is the date, in symbolic form, that the bindfile was last modified 
before being put into the binder's object archive. 
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SECTION 2 


STANDARD EXECUTION ENVIRONMENT 


STANDARD STACK AND LINK AREA FORMATS 


ee A A Sl 


Because of the linkage mechanism, stack manipulations, and the complexity 
of the Multics hardware, a series of Multics execution environment standards 
have been adopted. All standard translators (including assemblers) adhere to 
these standards as do all supervisor and standard storage system procedures. 
Furthermore, they assume that other procedures do so as well. 


Multics Stack 


The normal mode of execution in a standard Multics process uses a stack 
segment. There is one stack segment for each ring. The stack for a given ring 
has the entryname stack R, where R is the ring number, and is located in the 
process directory. Each stack contains a "header" followed by as many "stack 
frames" as are required by the. executing procedures. A stack header contains 
pointers to special code and data that are initialized when the stack is 
ereated. Some of these pointers are variable and change during process 
execution. They are included in the stack header so that they can always be 
retrieved without supervisor intervention (for efficiency). The actual format 
of the stack header is described under "Stack Header" below. 


Stack frames begin at a location specified in the stack header, are 
variable in length, and contain cotn control information and data for 
dynamically active procedures. In general, a stack frame is allocated by the 
procedure to which it belongs when that procedure is invoked. The stack frames 
are threaded to each other with forward and backward pointers, making it an easy 
task to trace the stack in either direction. The stack usage described below is 
eritical to normal Multics operation; any deviations from the stated discipline 
ean result in unexpected behavior. 


Stack Header 


The stack header contains pointers (on a per-ring basis) to information 
about the process, to operator segments, and to code sequences that can be used 
to invoke the standard call, push, pop, and return functions (described below). 
Figure 2-1 gives the format of the stack header. The following descriptions are 
based on that figure and on the following PL/I declaration. 
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+0 


Reserved 


+81tCombined 
Linkage 
Pointer 


+16 
INull 
Pointer 


+24 


+32 


Push’ Operator 


Pointer 


+40 
Translator 
Operator 
Pointer 


+48 


*system Link 
Info Pointer 


+56 


+64 


Stack Begin 


Pointer 


BAR Mode 
Stack Pointer 


Return Operator 
Pointer 


Internal Static 
Offset Table 
Pointer 


Reference 
Name Table 


iPointer 


Odd Lot 
Pointer 


System Storage 
Pointer 


Stack End 
Pointer 


PL/I Operators 


‘Pointer 


Short Return 
Operator Ptr 


System Condition 
Table Pointer 


Event Channel 
Table 
Pointer 


Reserved 


Figure 2-1. 


Stack Header Format 


Combined 
Static 
Pointer 


User Storage 
Pointer 


Lot 
Pointer 


Call Operator 
Pointer 


Entry Operator 
Pointer 


Unwinding 
Procedure 
Pointer 


Assign 
Linkage 
Pointer 
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del i stack header based aligned, 
2 padi(4) fixed bin, 
2 old lot ptr ptr, 
2 combined stat ptr ptr, 
2 clr_ptr ~ ptr, 
2 max lot size fixed bin(17) unaligned, 
2 run unit _depth fixed bin(17) unaligned, 
2 cur Ob: ‘Size fixed bin(17) unaligned, 
2 pad2 bit(18) unaligned, 
2 system storage ptr ptr, 
2 user _ storage __ ptr pur, 
eon, _ptr ptr, 
2 stack begin_ptr ptr, 
2 stack _end_ptr ptr, 
2 lot_ptr ptr, 
2 signal ptr ptr, 
2 bar_ mode Sp_ptr ptr, 
2 pli _operators_ ptr per, 
2 call Op_ptr per; 
2 push _ op_ptr ptrsy 
2 return __Op_ptr ptr, 
2 short return |_op_ptr ptr, 
2 entry_ Op_ pir pcr, 
2 trans op tv ptr ptr, 
22800 -ptr- «~ ptr, 
2 set ptr pers 
2 unwinder_ptr ptr, 
2 sys_ link_ info_ptr ptr, 
2rnt_ __ptr ptr, 
2 ect. _ptr ptr, 
2 assign linkage ptr ptr, 
2 pad3(8) fixed bin; 
wnere:? 
1. padi 
is unused. 
2. old lot _ptr 
~ is a pointer to the linkage offset table (LOT) for tne current ring. 
This field is obsolete. 
3. combined stat ptr is a pointer to the area in which separate static 
sections are allocated. 
4. clr ptr 
is a pointer to the area in which linkage sections are allocated. 
5. max lot size 
= is the maximum number of words (entries) that the LOT and internal 
static offset table (ISOT) can have. 
6. run_unit_depth 
is the current run unit level. 
7. cur_lot_size 
is the current number of words (entries) in the LOT and ISOT. 
8. pad2 
is unused. 
9. system Storage ptr 


is a pointer to the area used for system storage, which includes 
command storage and the *system link name table. 
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10. 


11. 


le. 


13. 


14. 


15. 


16. 


17. 


18. 


19. 


20. 


21. 


user storage ptr 
~ is a pointer to the area used for user. storage, which includes 
FORTRAN common and PL/I external static variables whose names do not 
inelude "$", 


null ptr 
contains a null pointer value. In some circumstances, the stack 
header can be treated as a stack frame. When this is done, the 
null pointer field occupies the same location as the previous stack 
frame pointer of the stack frame. (See "Multics Stack Frame" 
below.) A null pointer indicates that there is no stack frame prior 
to the current one. 


stack begin ptr 
is a pointer to the first stack frame on the stack. The first stack 
frame does not necessarily begin at the end of the stack header. 
Other information, such as the linkage offset table, can be located 
between the stack header and the first stack frame. 


stack _end_ ptr 
is a pointer to the first unused word after the last stack frame. 
It points to the location where the next stack frame is placed on 
this stack (if one is needed). A stack frame must be a multiple of 
16 words; thus, both of the above pointers point to 0 (mod 16) word 
boundaries. 


lot ptr 
a is a pointer to the linkage offset table (LOT) for the current ring. 
The LOT contains packed pointers to the dynamic linkage sections 
known in the ring in which the LOT exists. The linkage offset table 
is described below under "Linkage Offset Table." 


Signal ptr 
is a pointer to the signalling procedure to be invoked when a 
eondition is raised in the current ring. 


bar mode sp ptr 
7 is a pointer to the stack frame in effect when BAR mode was entered. 
(This is needed because typical BAR mode programs can change the 
word offset of the stack frame pointer register.) 


pl1_operators_ ptr 
is a pointer to the standard operator segment used by PL/I. It is 
used by PL/I and FORTRAN object code to locate the appropriate 
operator segment. 


call_op ptr 
is a pointer to the Multics standard call operator used by ALM 
procedures. It is used to invoke another procedure in the standard 
way. 


push op ptr 
~ Is a pointer to the Multics standard push operator that is used by 
ALM programs when allocating a new stack frame. All push operations 
performed on a Multics stack should use either this or an equivalent 
operator; otherwise results are unpredictable. (The push operation 
was formerly called save.) 


return_op ptr 
is a pointer to the Multics standard return operator used by ALM 
procedures. It assumes that a push has’ been performed by the 
invoking ALM procedure and pops the stack prior to returning control 
to the caller of the ALM procedure. 


short_return_op ptr 
™~ is a pointer to the Multics standard short return operator used by 
ALM procedures. It is invoked by a procedure that has not performed 
a push to return control to its caller. 
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22. entry op ptr 
is a pointer to the Multics standard entry operator. The entry 
operator does little more than find a pointer to the invoker's 
linkage section. 


23. trans op _tv_ptr 
~ points to a vector of pointers to special language operators; this 
table can be expanded to accommodate new languages without causing a 
change in the stack header. 


24. isot ptr 
~ is a pointer to the internal static offset table (ISOT). The ISOT 
contains packed pointers to the dynamic internal static sections 
known. in the ring in which the ISOT exists. 


25. sct_ptr 
is a pointer to the system condition table (SCT) used by system code 
in handling certain events. 


26. unwinder_ptr 
is a pointer to the unwinding procedure to be invoked when a 
nonlocal goto is executed in the current ring. 


27. sys_link_info_ptr 
is a pointer to the *system link name table. 


28. rnt_ptr 
points to the reference name table (RNT). 


29. ect ptr 
points to the event channel table (ECT). 


30. assign linkage ptr 
points to the area used by certain critical system programs whose 
operations must not be modified by run unit. This pointer initially 
points to the same area as stack header.clr_ ptr but is not changed 
by the run unit mechanism. 


31. pad3 
is unused. 


The call, push, return, short return, and entry operators are invoked by 
the object code generated by the ALM assembler. Other translators that intend 
to use the standard call/push/return strategy should either use these operators 
or an operator segment with a set of operators consistent with these. For a 
detailed description of what the operators do and how to invoke them, see 
"Subroutine Calling Sequences" later in this section. 


The PL/I and FORTRAN compilers use slightly different operators that 
perform equivalent and compatible functions. All supported translators, 
however, depend on the effects generated by these operators. 


The format given below for a standard Multics stack frame must be strictly 
followed because several critical procedures of the Multics system depend on it. 
A bad stack segment or stack frame can easily lead to process termination, 
looping, and other undesirable effects. 


In the discussion that follows, the "owner" of a stack frame is the 
procedure that created it (with a push operation). Some programs (generally ALM 
programs) never perform a push and hence do not own a stack frame. If a 
procedure that does not own a stack frame is executing, it can neitner call 
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another procedure nor use stack temporaries; all stack information refers to the 
program that called such a program. 


Figure 


2-2 illustrates the detailed structure of a stack frame (the 


| standard use in ALM). The following descriptions are based on that diagram and 
on the following PL/I declaration. 


I stack frame +0 


T ! 


Pointer Register Storage 


+16} } | 


1 ' 
|Previous StackiNext Stack Return Entry 


' 1 
' I 
1 i 
\Frame Pointer |Frame Pointer} Pointer Pointer 
i] 1 i] ! 
i} i} 1 1 


+24} I \ 1 


| 
1 t 
iOperator i Argument jInternal | ** {On Unit {Operator 
{Linkage {Pointer Static iRelative {Return 
iPointer {Pointer | 'Pointer {sOffset 
1 I I ! ! | 
I I [ t i | 
+321 
| 
i) 
Register Storage 
{ 
i 
+40} 
| Temporaries 
1 
! 
H 
¥* Reserved 
Figure 2-2. Stack Frame Format 
del 1 stack frame based (sp) aligned, 
2 prs(16) fixed bin, 
2 prev_stack frame ptr ptr, 
2 next stack frame ptr Der, 
2 return_ptr pir, 
2 entry_ptr ptr, 
2 operator _link_ptr ptr, 
2 argument ptr ptr; 
2 static ptr ptr unaligned, 
2 reserved fixed bin, 
2 on_unit_rel_ptrs(2) bit(18) unaligned, 
2 translator_id bit(18) unaligned, 
2 operator_return offset bit(18) unaligned, 
2 regs(8) fixed bin; 
where: 
1. prs 
is used to save pointer registers of the calling program when the 
ALM eall operator is invoked. 
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10. 


11. 


12. 


13 


prev stack frame ptr 
~ is a pointer to the base of the stack frame of the procedure that 
called the procedure owning the current stack frame. This pointer 
may or may not point to a stack frame in the same stack segment. 


next stack frame ptr 

~ is a pointer to the base of the next stack frame. For the last 
stack frame on a stack, the pointer points to the next available 
area in the stack where a procedure can lay down a stack frame; 
i.e., it has the same value as the stack end ptr in the’ stack 
header. The previous stack frame pointers and the next stack frame 
pointers form threads through all active frames on the stack. These 
- two threads are used by debugging tools -to search and trace the 

stack as well as by the call/push/return mechanism. 


return ptr 
“is a pointer to the location to which a return can be made in the 
procedure that owns the given frame. This pointer is undefined if 
the procedure has never made an external call, and points to the 
return location associated with the last external call if the given 
procedure has been returned to and is currently executing. 


entry ptr 
is a pointer to the procedure entry point that was called and that 
owns the stack frame. The pointer points to a standard entry point. 
See "Structure of the Text Section" in Section 1. 


operator link ptr 
is usually the operator pointer being used by the procedure that 
owns the given stack frame. For ALM programs, this points to the 
linkage section of the procedure. 


argument ptr 
is a pointer to the argument list passed to the procedure that owns 
the given stack frame. 


static ptr 
is a pointer to the internal static storage for the procedure owning 
the stack frame. 


reserved 
is reserved for future use. 


on_unit rel ptrs 

> is a pair of relative pointers to on unit information contained 
within the stack frame. This on unit information is valid only if 
bit 29 of the second word of prev stack frame ptr is a 1. (This bit 
is automatically set to 0 when a push is performed by the procedure 
that owns the stack frame.) The first of the on unit rel ptrs is a 
pointer (relative to the stack frame base) to a list of enabled 
conditions. The second of the on_unit rel ptrs is obsolete. 


translator id 
is a coded number indicating the translator used to generate the 
object code of the owner of the stack frame. 


operator return offset 
contains a return location for certain pl1_operators_ functions. If 
it is nonzero, it is a relative pointer to the return location in 
the compiled program (return from pl1 operators ). If it is zero, a 
dedicated register (known by pl1 operators ) contains the return 
location. . ~ 


regs 


is used to save arithmetic registers of the calling program when the 
ALM call operator is invoked. 
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Two major areas of a stack frame not explicitly defined above are the first 
16 words and words 32 through 39. The contents of these areas is not always 
defined or meaningful, although they have a well-defined purpose for ALM 
programs and are used internally by the PL/I and FORTRAN programs. The 
procedure owning the stack frame can use these areas as it sees fit. 


Linkage Offset Table 


As described above, each stack header contains a pointer to the linkage 
offset table (LOT) for the current ring. The LOT is an array, indexed by text 
segment number, of packed pointers to the linkage sections for the procedure 
segments known in the current ring. 


The structure of the LOT is defined by the following PL/I declaration: 


del 1 lot based (lot ptr) aligned, 
2 linkage ptr (0: stack _header.cur_lot_size-1) ptr unaligned; 


where linkage ptr is the array of linkage section pointers. 


If one of the slots in the linkage ptr array contains all 0's, the segment 
number associated with the slot either does not correspond to a known segment. 


If one of the slots in the linkage ptr array contains all O's except for 
"111"b in the high-order three bits (a lot fault), the segment number associated 
with the slot corresponds to a known segment that either does not have a linkage 
section or whose linkage section has not been combined (i.e., the segment has 
not been executed). 


Internal Static Offset Table 


The stack header in each ring contains a pointer to the internal static 
offset table (ISOT) for the current ring. The ISOT is an array, indexed by text 
segment number, of packed pointers to the internal static sections for the 
corresponding procedure segmentS Known in tne current ring. Since tne I1s50i 
always immediately follows the LOT, the isot ptr is redundant but is retained 
for efficiency. > 


The internal static pointers are identical to the linkage section pointers 
unless the corresponding object segment wasS generated with separate static. If 
the static is separate, i.e., not allocated in the linkage section, the internal 
Static pointer either points to the allocated static or contains a value that 
causes an “isot fault" if referenced. 


The structure of the ISOT is defined by the following PL/I declaration: 


del 1 isot based (isot_ptr) aligned, 
2 static ptr (0: stack_header.cur_lot_size-1) ptr unaligned; 


where static ptr is the array of static/linkage section pointers. 
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SUBROUTINE CALLING SEQUENCES 


The Multics standard call and return conventions are described in the 
following paragraphs. For information about the format of stack segments and 
Stack frames, see "Standard Stack and Linkage Area Formats" above. 


The call and return from one procedure to another can be broken down into 
seven separate steps. Operators to perform these steps have been provided in 
the standard operator segment named pl1 operators (for PL/I, FORTRAN, and ALM 
procedures). These operators are invoked when ‘appropriate by the object code 
generated by these translators. 


The steps involved in acall and return and the associated operators are 
listed below. 


Ws A procedure call, i.e., a transfer of control and passing of an 
argument list pointer to the called procedure (call). 


2 Generation of a linkage (and internal static) pointer for the called 
procedure (entry). 


34 Creation of a stack frame for the called procedure (push). 


4, Storage of standard items to be saved in the stack frame of the called 
procedure (entry and push). 


oe Release of the stack frame of the called procedure just prior to 
returning (return). 


6. Reestablishment of the execution environment of the calling procedure 
(return and short_return). 


ts Return of control to the calling procedure (return and short return). 


Preparation of the argument list, 


although necessary, was not listed above 
because the operators need know nothing about the format of an argument list. 
see "Argument List Format" later in this section 


Tne following description is based on the operators used by ALM procedures. 
The operators used by PL/I and FORTRAN procedures are basically the same but 
differ at a detailed level due to: (1) slight changes in the execution 
environment when PL/I and FORTRAN programs are running; and (2) simplification 
and combination of operators made possible by the execution environment of PL/I. 
The PL/I and FORTRAN operators are not described here other than to define a 
minimum execution environment that must be established when returning to a PL/I 
or FORTRAN program. 


(the following description is given in terms of Honeywell hardware.) 
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Call Operator 


The call operator transfers control to the called procedure. This operator 
is invoked in two ways from ALM procedures. The first is a result of the call 
pseudo-op, which invokes the call operator after saving the machine registers in 
the calling program's stack frame and loading pointer register 0 with a pointer 
to the argument list to be passed to the called procedure. Upon return to the 
calling program, these saved values are restored into the hardware registers by 
the calling procedure. The second way that ALM procedures can invoke the call 
operator is through the short call pseudo-op. This is used when the calling 
procedure does not need all of the machine registers saved and restored across 
the call. The ALM procedure can selectively save whatever registers are needed. 


Neither the call nor the short_call pseudo-ops (nor the PL/I and FORTRAN 
equivalents) require or expect the machine registers to be restored by the 
called procedure. In fact, only the pointer registers 0 (operator segment 
pointer) and 6 (stack frame pointer) are ever guaranteed to be restored across a 
call. It is up to the calling procedure to save and restore any other machine 
registers that are needed. 


Entry Operator 


The entry operator used by ALM programs performs two functions. It 
generates a pointer to the linkage section of the called procedure (which it 
leaves in pointer register 4) and it stores a pointer to the entry in what will 
be the stack frame of the called procedure (if the procedure ever creates a 
stack frame for itself). At the time the entry operator is invoked, a new stack 
frame has not yet been established. Indeed, the called procedure may never 
create one. However, it is certainly possible to know where the stack frame 
will go if and when it is created and this knowledge is used to store the entry 
pointer. 


The entry operator is invoked by an ALM procedure that transfers to a label 
in another procedure that has been declared as an entry through the entry 
pseudo-op. The transfer is made to a standard entry structure the first 
executable word of which is (PR7 is assumed to point to the base of the current 
stack segment): 


tsp2 7ientry op,* 


The operator returns to the instruction after the tsp2 instruction, which 
may or may not be another transfer instruction. (A link to the entry, when 
snapped, points to the tsp2 instruction.) See "Structure of the Text Section" 
in Section 1. 


Some ALM programs may not require a_ linkage pointer. Such:-programs can 
declare the label to which control should be transferred with a_ segdef 
pseudo-op. This causes the appropriate definition and linkage information to be 
generated so that other procedures can find the entry point. When called, the 
transfer is straight to the code at the label and the normal entry structure is 
not generated or used. No linkage pointer is found and no entry pointer is 
saved. This technique is recommended only where speed of execution is of utmost 
importance since it avoids calculation of useful diagnostic information. 
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Push Operator 


The push operator used by ALM procedures is invoked as a result of the push 
pseudo~op that is used to create a stack frame for the called procedure. In 
addition to creating a stack frame, several pointers are saved in the new stack 
frame. They are: 


® Argument pointer 

® Linkage pointer (and internal static pointer) 
@ Previous stack frame pointer 

e Next Stack frame pointer 


If the called procedure is defined as an entry (rather than segdef), the entry 
pointer has already been saved in the new stack frame. 


The push pseudo-op must be invoked if the called procedure makes further 
calls itself or uses temporary storage. Due to their’manner of execution, PL/I 
and FORTRAN procedures combine the entry and push operators into a single 
operator. 


The push operator and the return operators are managers of the stack frames 
and the stack segment in general. The push operator establishes the forward and 
backward stack frame threads and updates the stack end pointer in the stack 
header appropriately. The return operators use these threads and also update 
the stack end pointer as needed. Any program that wishes to duplicate these 
functions must do so in a way that is compatible with the procedures outlined in 
this discussion and those described above under the heading "Standard Stack and 
Linkage Area Formats". 


Return Operator 


The return operator is invoked by ALM procedures that have specified the 
return pseudo-op. The return operator pops the stack, reestablishes the minimum 
execution environment, and returns control to the calling procedure. The only 
registers restored are pointer registers 0 and 6, as mentioned above. 


Short Return Operator 


The short return operator is invoked by ALM procedures that have specified 
the short return pseudo-op. The short return operator differs from the return 
operator in that the stack frame is not popped. This return is used by ALM 
procedures that did not perform a push. 


Pseudo-op Code Sequences 


The following code sequences are generated by the assembler for the 
specified pseudo-op. 
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call: 


OBJECT CODE 


OPERATORS 


OBJECT CODE 


short_call: 
OBJECT CODE 
OPERATORS 
OBJECT CODE 
return: 


OBJECT CODE 
OPERATORS 


short_return: 


OBJECT CODE 
OPERATORS 


entry: 


OR IECT CODR 
OPERATORS 


OBJECT CODE 
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spri 
sreg 
eppo 
epp2 
tsp4 
spri4 
sti 
epp4 
call6 
lpri 
lreg 


epp2 
tsp4 


pr6{0 

pr6{32 

arglist 

entrypoint 

pr7istack header.call op,* 
pr6istack frame.return ptr 
pr6!stack frame.return _ptr+| 
préistack_ frame.lp ptr,* 
pr2}0 

pr6}0 

pr6{32 


entrypoint 
pr7istack header.call op,* 


(as above) 


epp4 


tra 
spri6o 
epp6 
epbp7 
eppO 
ldi 
rtca 


tra 
epbp7 
epp0 
ldi 
rted 


tn? 
eppe 
epp4 
spri2 
epaq 
Iprp5 
sprp5 
lprp4 
tra 


tra 


proistack frame.lp ptr,* 


pr7istack header.return_op, * 
pr7istack header. stack __ end por 
pr6istack_ frame.prev_sp,* 

pr6i0 

proistack_ frame.operator_ ptr,* 
pr6istack frame.return ptr+1 
pr6istack frame.return ptr 


pr7istack header.short_return_op,* 
pr6:0 

proistack_frame.operator ptr, * 
pr6istack_ frame.return_ptr+1 
pr6istack frame.return ptr 


pr7istack header.entry_op.* 
pr2i-1 

pr7istack_ header.stack_end_ptr,* 
pr4istack_ frame.entry_ ptr 
pr2i0 

pr7istack_ header.isot ptr, *au 
pr4utstack frame.static ptr 
pr7istack_ header.lot_ptr, *au 
pr2i1 

executable code 
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push: 


OBJECT CODE eaxT stack frame size 
tsp2 pr7istack _ header.push _op,* 
OPERATORS spri2 pr7istack | header. stack _ end ptr,* 
epp2 prTistack header. stack _ end ptr,* 
spri6 pr2istack frame.prev_sp 
sprio pr2istack_ frame.arg_ ptr 
spri4 pr2istack_ frame.lp ptr 
epp6 pr2io 
epp2 pr610,7 
spri2 pr7istack_ header.stack end ptr 
spri2 proé{stack frame.next_sp 
eaxT pr 
stx7 pr6\stack frame.translator id 
tra pr6{0,* 


Register Usage Conventions 


The following conventions, used in the standard environment, should be 
followed by any user-written translator. 


B The only registers that are restored across a call are the pointer 
registers: 


0 (ap) operator segment pointer 
6 (sp) stack frame pointer 


The operator segment pointer is restored correctly only if it is saved 
at some time prior to the call (e.g., at entry time). 


B The code generated by the ALM assembler assumes that pointer register 
4 (lp) always points to the linkage section for the executing 
procedure and that pointer register 7(sb) always points to the stack 
header. 


a Pointer register 7 is assumed to be pointing to the base of the stack 
when control is passed to a called procedure. 


Argument List Format 


When a standard call is performed, the argument pointer (pointer 
register 0) is set to point at the argument list to be used by the called 
procedure. The argument list must begin on an even word boundary. It's format 
is given by the following PL/I declaration (arg list.inel.pl1). 


del 1 arg list aligned based, 

2 arg count fixed bin(17) unsigned unal, 
2 padt biEC1)“unal, 

2 call_type fixed bin(18) unsigned unai, 
2 dese count fixed bin(17) unsigned unal, 
2 pad2 bit(19) unal, 

2 arg ptrs (arg list_arg count) ptr, 

2 dese _ptrs (arg list_arg count) ptr; 
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del 1 arg list _with_envptr aligned based, 


2 arg count fixed bin(17) unsigned unal, 
2 padi bit(1) unal, 
2 call type fixed bin(18) unsigned unal, 
2 dese _ count fixed bin(17) unsigned unal, 
2 pad2 bit(19) unal, 
2 arg ptrs (arg_list_arg count) ptr, 
2 envptr ptr, 
2 desc ptrs (arg list_arg count) ptr; 
0 16 17 18 
ie dca ae Meanie 
i Dacca, DON 
2 
4 


environment pointer (optional) 


Pointer to descriptor 1 


Pointer to descriptor 2 


Pointer to descriptor n 


Figure 2-3. Standard Argument List 


where: 


1. arg count 
is the number of arguments passed. 


2. padi 
is reserved and must be "0O"b. 
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py 


call _type 


is a code that describes the type of call being made. It can have 


one of the following values: 


6) 

for quick internal calls. 
4 

for inter-segment calls. 
8 


for calls where an environment pointer is passed. 


The include file declares constants with these values: 


del ( 
Quick_call_ type init(0), 
Interseg call type init(4),. 


Envptr_supplied_call type init(8), 
) fixed bin(18) unsigned unal int static 
options (constant); 


desc count 
is the number of argument descriptors being passed. If non-zero, 
must be the same as arg count. 


pad2 
is reserved and must be "0O"b. 


arg ptrs 
is an array of pointers to the arguments. 


envptr 
is the environment pointer for the procedure being called. It 
present only if call_type is &. 


desc _ptrs 
is an array of pointers to the argument descriptors, if present. 


it 


is 


NOTES: The pointers in the argument list need not be ITS pointers; however 
they must be pointers through which the hardware can perform 


indirect addressing. Packed (unaligned) pointers cannot be used. 


The pointer envptr is present when a call is made to a non-quick 
internal procedure or when a call is made through an entry variable, 
regardless of whether the procedure being called is an external or 
internal procedure. When the called procedure is an internal 
procedure, envptr points to a stack frame of the activation of the 
block that contains the called procedure, and is used to set up the 
display pointer for the stack frame that the non-quick procedure 
will create. If the call is made through an entry variable, envptr 
is copied from the environment ptr of the entry variable. (See the 
MPM Reference Guide for the format of an entry variable.) If the 
call is to an internal entry constant, envptr is calculated by the 
PL/I operators. If a call is made through an entry variable to an 
external procedure, the environment pointer of the entry variable 


will be null, thus envptr is aiso null. 


The include file also contains symbol names for the values that 
call type takes on. They are: Quick call _ type, Interseg call _ type, 


and Envptr_supplied_call_type. 


In the include file, the extent of the arrays, arg ptrs, and 


desc_ptrs is determined by the variable arg list_arg count ~ (which 


is 


not declared in the include file). In references to an already 


allocated argument list, the programmer should first 


set 


arg list_arg count to the value of arg count in the appropriate 


structure (arg | list or arg list with _envptr). 
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An argument pointer points directly to an argument. A descriptor pointer 
points to the descriptor associated with the argument. 


The format of an argument descriptor is described by one of the two 
following PL/I declarations, given in arg descriptor.incl.pll. 

del 1 arg descriptor based aligned, 

2 flag bit(1) unal, 

2 type fixed bin(6) unsigned unal, 

2 packed bit(1) unal, 

2 number dims fixed bin(4) unsigned unal, 

2 size fixed bin(24) unsigned unal; 
del 1 fixed_arg descriptor based aligned, 

2 flag bit(1) unal, 

2 type fixed bin(6) unsigned unal, 

2 packed bit(1) unal, 

2 number dims fixed bin(4) unsigned unal, 

2 scale — fixed bin(11) unal, 

2 precision fixed bin(12) unsigned unal; 


The first four elements have the same meaning for all data where: 


1. 


2 
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flag 


type 


always has the value "1i"b and is used to tell this descriptor format 
from an earlier format. (Shown as 1 in the descriptor below.) 


is the data type according to the standard descriptor types (see 
Appendix D of the MPM Reference Guide). Named constants for the 
descriptor types are declared in the std descriptor _types-.inel.pli 
include file. 
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3. 


4, 


packed 


has the value "1"b if the data item is packed. (Shown as "p" in 
typical descriptor below.) 


number dims 


wee wee ed eee ee 
— 


is the number of dimensions in an array. (Shown as "m" in 
descriptor below.) The array bounds and multipliers follow 
basic descriptors in the following manner: 


basic descriptor 
lower bound descriptive information 
upper bound 


for the mth 


multiplier (rightmost) dimension . 


SN Pd ak a ee ge el gee en eR ee oe es ew a 


lower bound descriptive information 


upper bound for the first 


multiplier (leftmost) dimension 


the 


the 
the 


If the data is packed, the multipliers give the element separation 


in bits; otherwise, they give the element separation in words. 


If the data is fixed-point, then: 


be 


6. 
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seale 


is a 2's complement, signed value. 


precision = 14 
is the number of bits used to represent the data (if binary) or the 


number of digits (if decimal). 
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For all other data: 


5. size 

. is the size (in bits, characters, or words) of string or area data, 
or the number of structure elements for structure data. In an argument 
descriptor for Algol68 array descriptor data, the size field is the 
number of dimensions of the array represented by the array decriptor 
datum. It is equal to the number dims field of the second datum of 
the Algol68& array descriptor datum. In an argument descriptor for 
Algol68 union data, the size field is the number of words in the 
Algol68& union datum. 


The descriptor of a structure is immediately followed by descriptors of 
‘each of its members. The example below shows a declaration (assuming that each 
element of C or D occupies one word) and its related descriptor. 


basic descriptor of S$ 
basic descriptor of A 
basic descriptor of B 
lower bound of B 

upper bound of B 
element separation of B 
basic separation of C 
lower bound of C 

upper bound of C 
element separation of C 
basic descriptor of D 
lower bound of D 

upper bound of D 
element separation of D 


Members of dimensioned structures are arrays, and their descriptor contains copies 
of the bounds of the containing structure. 


Parameter Descriptors 


The parameter descriptors associated with an entry point have the same 
format as argument descriptors. The value 16777215 (77777777 octal) in the size 
field of an area, bit, or character parameter indicates an asterisk size. The 
value -34359738368 (400000000000 octal) in the lower bound, upper bound, or 
multiplier fields indicates asterisk array bounds. 
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SECTION 3 


CLOSED SUBSYSTEM PROGRAMMING ENVIRONMENT 


WRITING A PROCESS OVERSEER 


Almost every feature of the standard Multics system interface can be replaced 
by providing a specially tailored process overseer procedure in place of the 
standard version. The standard Multics process overseer procedure, 
process overseer , is the initial procedure assigned to a user unless the project 
administrator specifies otherwise by an initproec or Initproc statement in the 
project master file (PMF). (See the Multics Administrators' Manual Project, 
Order No. AK51.) If a user has the v process overseer attribute, she may specify 
a different initial procedure when she logs in by using the -process overseer 
(-po.) control argument as in the following example: 7 


login Smith -po >udd>AEC>special overseer _ 


If Smith does not have the v_process overseer attribute, the system refuses the 
login. 


If the user has the v process overseer attribute, she may leave a program 
named "process overseer " in her homedir. Note that if the PMF specifies a 
reference-name other than "process overseer ", the user must put whatever it 
specifies in her homedir. If the PMF provides an absolute pathname for the 
initial procedure, the user can not replace it in this manner. 


Process Initialization 


A process is created for a user when she logs in, or in response to either 
a new proc command (described in the MPM Commands) or process termination signal. 
What follows is a brief description of the birth of a process. 


Unless otherwise noted, all of the modules described are in PL/I. It is 
helpful to follow along this discussion with a listing of the modules; the 
comments often provide useful amplification. To do so, use the library fetch 
command. For example: = 


lf initialize process .pl1 


Several items of information must be passed to all processes by the system 
control process. The system places this information in a special per-process 
segment, called the process initialization table (PIT), that resides in the 
process directory. The user process may read the contents of the PIT, but may 
not modify it because its write bracket is zero. The user info subroutine 
(described in the MPM Subroutines) is used to extract information from the PIT. 
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A process begins, for all intents and purposes, with a call to the ring 
zero routine init proc. This description will only mention those actions of 
init proe which are of significance to visible features of the user environment. 


The first action of init proc is to initialize the known segment table 
(KST) by calling initialize kst. Then init proce initializes the PIT, and checks 
for the v process overseer attribute. If v process overseer is on, init proc 
sets the working directory to the user's home directory. Until this point the 
user has no working directory, so that users without v process overseer do not 
get their home directory into the search rules until later on in their process. 
This prevents users without v process overseer from replacing their initial 
procedure, signaller, or unwinder. = 


Now init proc calls makestack to create the stack in the user's initial 
ring. First, makestack creates a segment named stack N in the process directory, 
where N is the number of the user's initial ring. It fills in the null pointer, 
begin pointer, and end pointer of the stack and calls the linker (via 
link man$get initial linkage), to get the initial linkage for the ring. 


The internal procedure initialize rnt is then called by makestack in order 
to make a reference name table (RNT) for the ring in question. initialize rnt 
calls define area to get an area for the RNT, and puts a pointer to the RNT 
into the appropriate place in the stack header. Then initialize rnt initializes 
the search rules to the default rules and returns. a 


At this point makestack adds the name of the stack it is creating to the 
RNT and calls the linker to snap links to signal , unwinder , the alm operators, 
and pl1 operators . Thus users with v process overseer, whose working directories 
were set by init proc before makestack was called, pick up any versions of these 
programs that are resident in their home directories. It then sets up the 
static condition handlers for no write permission, not in write bracket, 
isot fault, and lot fault, fills in the thread pointers for the first stack 
frame and returns. ~— 


Now, init proce is ready to find the initial procedure. For the purposes of 
this discussion, the initial procedure is the first procedure called in the 
user's initial ring. The term "process overseer" will refer to the program 
specified by the initproc keyword of the PMF or the argument to the -process overseer 
control argument of the login access request. If the string ",direct" is appended 
to the pathname specified by either the initproc keyword or the -process overseer 
eontrol argument, then the specified pathname is both the process overseer and 
the initial procedure and init proc parses the pathname and initiates it explicitly. 
This is because link snap$make ptr (the ring 0 entry that snaps links) will not 
take absolute or relative pathnames. Therefore init proce parses the supplied 
pathname as either an absolute pathname or a relative pathname relative to the 
user's home directory. Note that this is independent of the state of 
v process overseer -- if the project administrator specified a ,direct overseer 
with a relative pathname, it will reference off of the home directory. This 
primarily provides a typing convenience to users with v process overseer specifying 
a ,direct overseer at login. If the name does not end with ,direct, the standard 
initial procedure, initialize process , is used. 
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At this point init proc either has a pointer and a reference name for a j 
,direct overseer, or it has a reference name to the standard initial procedure * 
initialize process . 


Finally, init proc calls call outer ring to call out to the user's initial 
ring. Note that a user without v process overseer is still lacking a working 
directory. It is the responsibility of any user-supplied ,direct initial procedure 
to set the working directory. 


The user's process now begins execution in the initial ring in the program 
initialize process . 


v process overseer it finds the appropriate process overseer. Then it sets the 
working directory, and finds the process overseer if it was not previously found. 
It sets up static condition handlers for cput, alrm, trm_, wkp_ and sus. 


The initialize process procedure first initiates the PIT. If the user lacks | 


Before calling the process overseer, initialize process attaches the I/0 i 
switch named user i/o (through an I/O system module named in the PIT) to the 
target (also specified jn the PIT). It then attaches the I/O switches named 
user output, user input, and error output as synonyms of user i/o by calling 
iox $init standard iocbs. The I/0 module used for an interactive process is 
tty , the Multics terminal device I/O module. (This module is described in the 
MPM Communications I/0.) For absentee processes it is abs io _, and for daemons | 
it is mr . 


The initialize process _ procedure then calls the process overseer specified 
in the PIT. This is either the procedure specified in the "initproc" keyword of 
the PMF, or the -po argument to login. It is called with the following arguments: 

declare process overseer_ entry (ptr, bit (1) aligned, char (*) varying); 


call process overseer (pit ptr, call listen _, initial cl); 


where: 

1s pit ptr (Input) 
is a pointer to the PIT. It should be ignored. 

2% call listen_ (Output) 
if set to "1"b, initialize process will call listen with the value 
of initial cl as the first command line, thus star€ing the command 
environment. If it is set to "0"b , the process will be terminated, 
on the assumption that the process overseer already ran the entire 
process. 

3. initial el (Output) 


Is the first command line to be executed, normally an exec com of 
the start_up ec. It may be up to 256 characters long. - 
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Process Overseer Functions 


x 
The system process overseers terminate processing by setting the call listen 
flag in their calling sequence, setting the initial cl argument to the initial 
command line, and returning to initialize process . 


A user-supplied process overseer procedure may perform many other actions 
besides those executed by the system version. For example, initialization of 
special per-project accounting procedures may be accomplished at this point, or 
requests issued for an additional password or any other administrative information 
required by a project. 


The initial command line used by the system process overseer is: 


j exec com start up path>start up.ec start type proc type 


where: 


1. start_up path 
is the location of the user's start up.ec. The system process overseers 
search for the start up.ec in fhe following directories, in this 
order: >udd>Project>person, >udd>Project, and >system control 1. 


2. start type 
~ is either login or new proc, depending on which of these was invoked 
to create the process. 


3. proc type 
~ ds either interactive, absentee, or daemon. 


These arguments can be used by the start up.ec segment as described in 
connection with the exec com command in the MPM Commands. 


The command line given above assumes that the no start up flag is off and 

% that the segment named start up.ec can be found. The no start up flag is off 

unless the project administrator has given the user the no start _up attribute 

and the user has included the proper control argument (- no Start _up or -ns) in 
his login line. 


If the process overseer returns to initialize process with the call listen 
flag set, initialize process establishes an any other handler of 
default error handler $wall by executing the statement: ~ 


on any other call wall entry variable; 


An entry variable is used because initialize process calls hes $make entry 
with a null referencing pointer, so that users with v process overseer can put 
private versions of default _error handler_ in their homedirs. ~ 


| The default error handler $wall procedure is invoked on all signals not 
intercepted by any subSequently established condition handler. In general, the 

i default error handler $wall procedure either performs some default action (such 
as inserting a pagemark into the stream when an endpage condition is Signalled) 
and restarts execution, or else it prints a standard error message and calls the 
current listener. 


If the process overseer does not use the call listen flag, it must establish 
its own any other handler, and call the listener if cleared. 
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Some Notes on Writing a Process Overseer 


The best source of information on the writing of process overseers is the 
source of the standard one: process overseer .pl1. There are, however, several 
important considerations not obvious from the source. 


The first is that process overseer makes use of the pointer to the PIT 
that it gets as an argument. This means that if the PIT format changes, at best 
process overseer must be recompiled. At worst, it may have to be recoded. If 
a user process overseer uses the PIT instead of calling user info , then it will 
likely stop working if the format of the PIT changes. For this reason, we 
strongly recommend that user-written process overseers do not directly reference 

the PIT. They should call user_info , instead. 


Both of the installed process overseers look for start up exec coms. The 
process overseer and project start up procedures try to find start up.ee in 
the home directory, the project directory, and >sc1 before giving up. “Privately 
written process overseers should do so as well, unless they are putting the user 
in an environment for which this is obviously inappropriate. 


Direct Process Overseers 


The ,direct overseers are called as the first procedure in the user ring. 
In addition to setting up all I/0 attachments for user i/o, and static condition 
handlers for alrm, cput, trm , wkp and sus , ,direct overseers are responsible 
for setting the working directory for users without v process overseer. This is 
done to make protection somewhat easier, as the ,direct overseer can find anything 
it is interested in before setting the working directory. 


Handling of Quit Signals 


A quit signal is indicated by pressing the appropriate key, such as ATTN or 
BRK, on the terminal in use. When a terminal is first attached for interactive 
processing, quit signals from the terminal are disabled. A user quit signal 
issued at this time causes the flushing of terminal output buffers, but the quit 
condition is not raised in the user ring. The recognition of quit signals is 
enabled when the following call is made: 


call iox $control (iox $user io, "quit enable", null(), status); 


If a project administrator wishes to replace the standard user environment 
with his own programs, he must find an appropriate place for the quit enable 
order, after the mechanism for handling quit signals has been established. 
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SECTION 4 


IMPLEMENTATION OF INPUT/OUTPUT MODULES 


This section contains information applicable to writing I/O modules. It 
describes the format and function of I/0 control biocks, and provides a list of 
implementation rules. For descriptions of the iox_ entry points, refer to the 
MPM Subroutines, and to the iox_$init standard_iocbs entry point description in 
this manual. 


Some instances in which a user might wish to create a new I/O module are 
given below: 


le Pseudo Device or File. An I/O module could be used to simulate I/0 
to/from a device or file. For example, it might provide a sequence of 
random numbers in response to an input request. The discard _ system 
I/O module (described in the MPM Subroutines) is an example of this 
sort of module. 


rae New File Type. An 1/0 module could be used to support a new type of 
file in the storage system, such as a file in which records have 
multiple keys. 


3% Reinterpreting a File. An I/0 module could be designed to overlay a 
new structure (relative to the standard file types) on a standard type 
of file. For example, an unstructured file might be interpreted as a 
sequential file by considering 80 characters as a record. 


4, Monitoring a Switch. An 1/0 module could be designed to pass 
operations along to another module while monitoring them in some way 
(e.g., by copying input data to a file). The audit _ system I/O module 
(described in the MPM Subroutines) is an example of this sort of I/0 
module. 


5. Unusual Devices. Working through the tty_ 1/0 module (described in 
the MPM Subroutines) in the raw mode, another I/0 module might 
transmit data to/from a device that is not a standard Multics device 
type (as regards character codes, etc.). 


The last three items listed illustrate a common arrangement. The user 
attaches an I/O switch, x, using an I/O module, A. To implement the attachment, 
module A attaches another switch, y, using another I/O module, B. When the user 
calls module A through the switch x, module A in turn calls module B through the 
switch y. Most nonsystem I/O modules that perform true I/O work in this way, 
because a nonsystem I/O module (or some module that it calls) in turn calls a 
system I/O module. There are system I/O routines at a more primitive level than 
the I/O modules, but user-written I/O modules must not call these routines. 


I/O CONTROL BLOCKS 


Each I/0 switch has an associated I/O control block that is created the 
first time a call to iox_$find_iocb requests a pointer to the control block. 
The control block remains in existence for the life of the process unless 
explicitly destroyed by a call to iox_$destroy_iocb. 
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The principal components of an I/O control block are pointer variables and 
entry variables whose values describe the attachment and opening of the I/0 
switch. There is one entry variable for each I/O operation with the exception 
of the attach operation, which does not have an entry variable since there can 
be only one attach entry point in an I/O module. To perform an I/O operation 
through the switch, the corresponding entry value in the control block is 
called. For example, if iocb ptr is a pointer to an I/O control block, the 
calls 


eall iox_$put_chars (iocb_ptr, buff_ptr, buff_len, code); 
can be thought of as: 
call iocb_ptr->iocb.put_ chars (iocb ptr, buff_ptr, buff_len, code); 


Certain system routines make the latter call directly, without going through the 
appropriate icx_ subroutine; all other routines must call the iox_ subroutine, 
as the internal representation of the control block may change. 


I/O Control Block Structure 


The declaration given below describes the first part of an I/O control 
block. Only those few I/O system programs that use the remainder of the I/0 
control block declare the entire block. Thus, all references to I/0 control 
blocks here refer only to the first part of the control block. For example, the 
statement "no other changes are made to the control block" means that no other 
changes are made to the first part of the control block, and so on. The I/O 
system might make changes to the remainder of the block, but these are of 
interest only to the I/0 system. For full details on the entry variables, see 
the descriptions of the corresponding entries in the iox_ subroutine in the MPM 
Subroutines and the iox_$init standard_iocbs entry point in this manual. This 
structure is given in iocb-.incl.pli. 


del 1 ioeb aligned, 

2 iocb_version fixed bin init(1), 

2 name char(32), 

2 actual_iocb ptr ptr, 

2 attach descrip ptr ptr, 

2 attach_data ptr pers 

2 open_descrip ptr per, 

2 open_data ptr Puts 

2 reserved pity 2); 

2 detach_iocb entry (ptr, fixed bin(35)), 

2 open entry (ptr, fixed bin, bit(1) aligned, 
fixed bin(35)), 

2 close entry (ptr, fixed bin(35)), 

2 get_line entry (ptr, ptr, fixed bin(21), fixed bin(21), 
fixed bin(35)), 

2 get chars entry (ptr, ptr, fixed bin(21), fixed bin(35)), 

2 put chars entry (ptr, ptr, fixed bin(21), fixed bin(35)), 

2 modes entry (ptr, char(*), char(*), fixed bin(35)), 

2 position entry (ptr, fixed bin, fixed bin(21), 
fixed bin(35)), 

2 control entry (ptr, char(*), ptr, fixed bin(35)), 

2 read_record entry (ptr, ptr, fixed bin(21), fixed bin(21), 
fixed bin(35)), 

2 write_record entry (ptr, ptr, fixed bin(21), fixed bin(35)), 

2 rewrite record entry (ptr, ptr, fixed bin(21), fixed bin(35)), 

2 delete record entry (ptr, fixed bin(35)), 

2 seek key entry (ptr, char(256) varying, fixed bin(21), 
fixed bin(35)), 

2 read_key entry (ptr, char(256) varying, fixed bin(21), 
fixed bin(35)), 

2 read_length entry (ptr, fixed bin(21), fixed bin(35)); 


7/81 4-2 AK92C 


If the I/0 switch is detached, the value of iocb.attach_descrip ptr is 
null. If the I/O switch is attached, the value is a pointer To the following 
structure: 


del 1 attach descrip based aligned, 
2 length fixed bin(17), 
2 string char (0 refer (attach descrip.length)); 


The value of attach descrip.string is the attach description. See "Multics 
Input/Output System" in Section 5 of the MPM Reference Guide for details on the 
attach description. 


If the 1/0 switch is detached, the value of iocb.attach data ptr is null. 
If the I/O switch is attached, the value may be null, or it may be a pointer to 
data used by the I/0 module that attached the switch. To determine whether the 
I/O switch is attached or not, the value of iocb.attach descrip ptr should be 
examined; if it is null, the switch is detached. ~ ~ 


Open Pointers 


If the I/O switch is closed (whether attached or detached), the value of 
iocb.open_descrip ptr is null. If the switch is open, the value is a pointer to 
the following structure: 


del 1 open_descrip based aligned, 
2 length fixed bin(17), 
2 string char (0 refer (open_descrip.length)); 


The value of open_descrip.string is the open description. It has the 
following form: 


we 


mode {info 


where: 
Ls mode 
is one of the opening modes (e.g., stream_input) listed below. The 
modes and their corresponding numbers are: 
1 stream_input 
2 .stream_output 
3 stream input output 
4 sequential_ input 
5 sequential output 
6 sequential input_output 
7 sequential update 
8 keyed _sequéntial_ input 
9 keyed_ sequential output 
10 keyed sequential update 
11 direct input 
12 direct output 
13 direct update 
2. info 


is other information about the opening. If info occurs in the 
string, it is preceded by one blank character. 


4-3 AK92 


If the I/O switch is closed, the value of iocb.open_data_ ptr is null. If 
the I/O switch is open, the value may be null, or it may be a pointer to data 
used by the I/0 module that opened the switch. The iox modes.incl.pl1 include 
file gives standard names and named constants for the opening modes. 


Entry Variables 


The value of each entry variable in an I/O control block is an entry point 
in an external procedure. When the I/0 switch is ina state that supports a 
particular operation, the value of the corresponding entry variable is an entry 
point that performs the operation. When the I/0 switch is in a state that does 
not support the operation, the value of the entry variable is an entry point 
that returns an appropriate error code. The iox_ subroutine provides four error 
entries that set the error code argument for the I/0 module entry to an 
appropriate error_table value. The entries and the corresponding error codes 
are: 


iox_$err_not_attached (error_table $not_attached) 

iox_$err_not_closed Cerror_table $not_closed) 

iox_$err_no_operation (error_table $no_ operation) 

iox_$err_not_open (error_table $not_open) 
synonyms 


When an I/O switch named x is attached as a synonym for an I/O switch named 
y; the :vaiues of all entry variables in the I/0 control block for x are 
identical to those inthe I/0 control block for y with the exception of 
locb.detach. Thus a call: 


call ioebx_ptr->iocb.op(iocbx_ptr,...); 


immediately goes to the correct routine. 


The values of iocb-open descrip ptr and iocb-open _data_ptr for x are also 
the same as those for y. Thus, the I/O routine has access to its open data (if 
any) through the I/O control block pointed to by iocbx ptr. 


The value of iocb.actual_iocb ptr for x is a pointer to the control block 
for the last switch in a chain of switches that have been connected to each 
other by the syn I/0 module. (When the switch x is not attached as synonyn, 
this pointer points to the control block for x itself.) I/O modules use this 
pointer to access the actual I/0 control block whose contents are to be changed, 
for example, when a switch is’ opened. The I/O system then propagates the 
changes to any other control blocks that have been attached as synonyms to the 
actual I/O control block. 


WRITING AN I/O MODULE 


The information presented in the following paragraphs pertains’ to the 
design and programming of an I/O module. In particular, conventions are given 
that must be followed if the I/0 module is to interface properly with the I/0 
system. The reader should be familiar with the material presented under the 
headings "Multics Input/Output System" and "File Input/Output" in Section 5 of 
the MPM Reference Guide, the iox subroutine in the MPM Subroutines, and under 
"T/O Control Blocks" above. 7 
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Design Considerations 


Before programming begins on an I/O module, the functions it is to perform 
should be clearly specified. In particular, the designer should list the 
opening modes to be supported and consider the meaning of each I/0 operation 
supported for those modes. (See "Open Pointers" above for a list of opening 
modes.) The specifications in the description of the iox subroutine must be 
related to the particular I/O module (e.g., what seek key means for the discard 
I/O module). ~ 
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An I/0 module contains routines to perform attach, open, close, and detach 
operations and the operations supported by the opening modes. Typically, though 
not necessarily, all routines are in one object segment. If the module is a 
bound segment, only the attach entry need be retained as an external entry. 
Other routines are accessed through entry variables in I/O control blocks. 


An I/O module may have several routines that perform the same function but 
in different situations (e.g., one get line routine for stream input openings, 
another for stream_input_output openings). Whenever the situation changes 
(e.g., at opening), the module stores the appropriate entry values in the I/0 
control block. 


Implementation Rules 


The following rules apply to the implementation of all I/0 operations. 
Additional rules that are specific to a particular operation are given later. 
In the rules, ioecb is a based variable declared as described under "I/O Control 
Blocks" above, and ioccb ptr is an argument of the operation in question. 


1. Except for attach, the usage (entry declaration and parameters) of a 
routine that implements an I/O operation is the same as the usage of 
the corresponding entry in the iox subroutine. see the MPM 
Subroutines for details on the iox_ subroutine and the 
iox_$init_standard_iocbs entry point described in this manual. 


ae Except for attach and detach, the actual I/O control block to which an 
operation applies (i.e., the control block attached by the called I/0 
module) must be referenced using the value of 
iocb_ptr->iocb.actual_iocb ptr. It is incorrect to use just iocb_ ptr, 
and it is incorrect to remember the location of the control block from 
a previous call (e.g., by storing it in a data structure pointed to by 
iocb.open_data_ ptr). 


3% On entry to an I/0 module, the value of iocb_ptr->iocb.open data _ptr 
always equals the value of: 


The value of iocb_ptr->iocb.open descrip ptr always equals the value 
of: 


iocb_ptr->iocb.actual_iocb ptr->iocb.open descrip ptr 


Thus, the data structures related to an opening may be accessed 
without going through iocb-.actual_iocb ptr. 


u, If an I/O operation changes any values in an I/O control block, it 
must be the actual I/O control block (Rule 1 above). Many I/O modules 
mask ips signals when the iocb is being modified. To do this: 


ae Get ready to change the iocb by copying all pointers or entries 
that the new ioeb will contain into automatic variables. This 
will snap links to lessen the probability of a linkage error 
while interrupts are masked. 


b. Establish an any other handler to call terminate_process_ with 


error table $unable_to_do_io or some other appropriate status 
code. 
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Cc. Execute the call: 


call hes $set_ips mask (0, mask); 


The routine hes $set_ips mask is used to disable one or more ips 
interrupts. (See the description of hes $set_ips mask in this 


manual.) 
d. Change the iocb. 
e. Execute the call: 
call iox $propagate (p); 


where p points to the changed control block. 


The routine 


iox Spropagate reflects changes to other control blocks attached 


as synonyms. It also makes certain adjustments to 


the entry 


variables in the control block when the I/O switch is attached, 


opened, closed, or detached. 


f.. Execute the call: 


hes $reset_ips mask (mask, mask); 


This routine is used to enable one or more ips interrupts. 
the description of hes $reset_ips mask in this manual.) 


All I/O operations must be external procedures. 


4-5.) 


(See 


AK92A 


THIS PAGE INTENTIONALLY LEFT BLANK 


7/81 AK92C 


Attach Operation 


The name of the routine that performs the attach operation is derived by 
concatenating the word "attach" to the name of the I/0 module (e.g., 
discard attach is the name of the attach routine for the discard I/O module). 
Each attach routine has the following usage: ~ 


declare module nameattach entry (ptr, (*)char(*) varying, bit(1) aligned, 
fixed bin(35)); 


call module _nameattach (iocb ptr, option_array, com_err_switch, code); 


where: 

1. iocb_ptr (Input) 
points to the control block of the I/0 switch to be attached. 

2s option_array (Input) 
contains the options in the attach description. If there are no 
options, its bounds are (0:0). Otherwise, its bounds are (1:n) 
where n is the number of options. 

cir com_err_ switch (Input) 
indicates whether the attach routine should call the com_err_ 
subroutine (described in the MPM Subroutines) when an error is 
detected. 
"qb yes 
WONDH no 

4, code (Output) 


is a standard status code. 


The following rules apply to coding an attach routine: 


1. Lf the 1/0 switch is already attached Cisiarg if 
iocb_ptr=->iocb.attach descrip ptr is not null), return the code 
error table $not detached; do not make the attachment. 


2. If, for any reason, the switch is not and cannot be attached, return 
an appropriate nonzero code and do not modify the control block. Call 
the com_err_ subroutine if, and only if, com_err_switch is "1"b. If 
the attachment can be made, follow the remaining rules and return with 
code set to 0. 


oar Set iocb ptr->iocb.open and iocb ptr->iocb.detach iocb to the 
appropriate open and detach routines. In addition, set 
iocb_ptr->attach descrip ptr to point to a structure as described in 
"I/O Control Blocks" above. The attach description in this structure 
must be fabricated from the options in the argument option array, and 
there may be some modification of options, e.g., expanding a pathname. 


4, If desired, set iocb ptr->iocb.attach data ptr, iocb ptr->iocb.modes, 
and iocb_ptr->iocb.control. |= Make no _ other modifications to the 
control block. 


ee Call iox_$propagate. 
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Open Operation 


An open operation is performed only when the actual I/O switch is attached 
(through the I/0 module containing the routine) but not open. The following 
rules apply to coding an open routine: 


ie 


If, for any reason, the opening cannot be performed, return. an 
appropriate code and do not modify the I/0 control block. If the 
opening can be performed, follow the remaining rules and return with 
code set to Q. 


Set iocb_ptr->iocb.actual iocb ptr->iocb.op (where op is any operation 
listed under "Open Pointers" above) to an appropriate routine. This 
applies for each operation allowed for the specified opening mode. 
The following is a list of possible I/O operations: 


detach iocb 
open — 
elose 

get line 

get chars 

put chars 
modes 
position 
eontrol 
read_record 
write record 
rewrite record 
delete record 
seek key 

read key 

read length 


If either the modes operation or the control operation is enabled with 
the I/0 switch attached but not enabled when the switch is open, set 
iocb_ptr->iocb.actual_iocb ptr->iocb.op (where op is modes or control) 
to iox_$err_no_ operation. 


Set open_descrip ptr to point to a structure as described in "I/0 
Control Blocks" above. 
If desired, set iocb ptr->iocb.actual_iocb _ptr->iocb.open_data_ptr. 


Do not make any other modifications to the control block. 


Call iox_$propagate. 


Close Operation 


A close operation is performed only when the actual I/O switch is open, the 
opening having been made by the I/O module containing the close routine. The 
following rules apply to coding a close routine: 


1. 


Set the following to the appropriate open and detach routines: 


iocb_ptr->iocb.actual_ iocb_ptr->iocb.open 
jiocb _ptr->iocb. actual _ iocb | _ptr->iocb.detach_iocb 


set iocb_ptr->iocb.actual_iocb_ptr->iocb.open_descrip ptr to null. 


If either the modes operation or the control operation is not enabled 
with the switch open and should be enabled with the switch closed, set 
iocb_ptr->iocb.actual_iocb_ ptr->iocb.op, where op is modes or control. 

If the operation is not enabled with the switch closed, set the entry 
variable to iox_$err_no_operation. 
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3% Do not make any other modifications to the control block. 

4, The close routine should set the bit counts on modified segments of a 
file, free any storage allocated for buffers, etc., and in general, 
clean things up. 


Sr The close routine must not return without closing the switch. 


Gers Call iox $propagate. 


Detach Operation 


A detach operation is performed only when the actual I/O switch is attached 
but not open, the attachment having been made by the I/O module containing the 
detach routine. The following rules apply to coding detach routines: 


Ts Set iocb_ptr->iocb.attach descrip ptr to null. 
2s Do not make any other modifications to the control block. 
3% The detach routine must not return without detaching the switch. 


4, Call iox_$propagate. 


Modes and Control Operations 


These operations can be accepted with the I/O switch attached but closed; 
however, it is generally better practice to accept them only when the switch is 
open. 


If the control operation is Supported, it must return the code 
error table $no_operation when given an invalid order. In this situation, the 
state of the I/O switch must not be changed. 


If the modes operation is supported, Lt. must 
error_table $bad_mode when given an invalid mode. in this 
of the I/O switch must not be changed. 


Performing Control Operations From Command Level 


Most of the operations supported by an I/O module may be used directly from 
command level by using the io_call command (see the MPM Commands). When a 
control operation requires an info structure see iox $control, MPM Subroutines. 
A special interface the "io call" order, is used to make these control 
operations from command level possible. All standard I/O modules that implement 
control operations requiring info structures should implement this interface, as 
described below. 


When an io_call command of the form: 


io_call control switch name {optional _ args} 


is issued, the io_call command performs an "io_call" control operation to the 
Switch specified using the following info structure (found in 
io_call_info.incl.pii): 
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where: 


1. 


del 1 io _call_info aligned based (io call infop), 
2 version fixed bin, a ~ 
2 caller_name char (32), 
2 order_name char(32), 
2 report entry options (variable), 
2 error entry options (variable), 
2 af_returnp per; 
2 af_returnl fixed bin, 
2 tall (5) bit( 36), 
2 nargs fixed bin, 
2 max_arglen fixed bin, 
2 args (O refer (io call info.nargs)) 
char (0 refer (To: : call_info.max_arglen)) 
varying; 
version 
is the version number of this structure, currently 1. 
caller name 
is the name of the caller (normally io_call) to be used in any error 
message or output. 
order_name 
is the order specified in the command line. 
report 
is an entry like ioa_ to be called to report the results of the 
order. 
error 
is an entry like com_err_ to be called to report any errors. 
af _returnp 
is a pointer to the active function return string if the io call 
command was invoked as an active function. 
af returnl 
— is tne maximum length of tne active function return string 
nargs 
is the number of optional args specified in the command line. 
max _argien 
is the length of the longest argument. 
args 
is an array of the actual arguments from the command line. 
The I/0 module, upon receipt of an io call order, should do the following: 
ts If io call info.order name specifies an order that requires an info 
structure “with input values, the I/0 module should use 
io_call_info.args to determine what data should be placed into the 
info structure. Once the structure is complete, the I/O module should 
call iox_$control, passing it io_call_info.order_name and a pointer to 
the info structure just created. Exactly how io_call_info. args is to 
be interpreted in order to build the info structure depends on the I/0 
module and what order is being performed. This should be documented 
along with the I/0 module. 
2. If io_call_info.order_name specifies an order that requires an info 


structure with output values, the I/0 module should call iox_$control 
passing it io call info.order_ name and a pointer to a structure of the 
appropriate kind. Then, using io call info.report, the I/O module 
Should display the results of the control operation in some meaningful 
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way. It is possible in this case that io call info.args could be used 
for control arguments to determine exactly what will be displayed. As 
in input type orders, the interpretation of these arguments is 
completely at the discretion of the I/0 module. 


oe If io call _info.order_ name specifies an order that does not require an 
info structure, or is an invalid order, then the I/0 module should 
return error table $undefined order request. The io call command, 


seeing this code, will call iox $control again, this time passing the 
original control order name, and a null info ptr. 


A If the I/0 module detects an error in handling an io call order, it 
must do one of two things. First, it may return an error code, in 
which case io call prints an error message. Secondly, it may call 
io call info. error (used like the com _err_ subroutine) to report the 
error directly. In this case, a zero error code should be returned to 
the caller. The latter choice is recommended, especially in cases 
where the I/O module can print a more informative error message. 


I/O modules that do not support control operations that require info 
structures need not implement the io call order at all. The io call order can 
be rejected along with all other invalid orders in which case the order is 
performed with a null info ptr by the io call command as described in item 3 
above. 


Control operations can also be performed through the active function 
interface of the io call command. In this case, the mechanism is basically the 
same with the following differences: 


Ts The order issued by the io call command is io call _ af, not io call. 


2. Instead of printing a result, the I/O module should store its result 
in the varying string defined by io_cali_info.af_returnp and 
io call info.af_returnl. 


The io call af order should only be supported for orders that have meaning 
as an active function. As in the io call order, the interpretation of 
io _call_info.args is completely up to the I/O module. 


Other Operations 


Routines for the other operations are called only when the actual I/0 
switch is attached and open in a mode for which the operation is allowed, the 
opening and attachment having been made by the I/0 module containing the 
routine. The following modifications to the I/0 control block of the actual 1/0 
switch can be made: 


1. Reset iocb ptr->iocb.actual iocb ptr-—>iocb.open data ptr. 


2. Reset an entry variable set by the open routine, e.g., to switch from 
one put_chars routine to another. 


on Close the switch in an unrecoverable error situation. In this case, 
the rules above for the close operation must be followed. 
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Outer Modules 


The iox I/O module with which user i/o is attached at process 
initialization is called the outer module. In order to support reconnection of 
terminals, I/O modules used as outer modules must respect certain conventions. 
For an example of the appropriate techniques, examine the source of tty _. 


All outer modules must support the -login_channel attach control argument, 
to mean that the switch will be connected to the device specified by 
user info $terminal_data. 


When the user is disconnected, the special condition sus_ is signalled in 
the process. The program sus_ signal handler eatches the condition, and blocks 
awaiting notification from the Answering Service that a new terminal is 
available. This may happen at any time, even when the process is compute-bound. 
When sus_signal handler_ receives the notification, it searches the attach table 
for all switches with the control argument -login_ channel in their attach 
description. Each one is closed, detached, attached, and opened. 


The result of this is that an outer module may be interrupted in the middle 
of an operation, have its switch detached and closed, and be left to continue 
execution. Outer modules must be designed to avoid failure under these 
circumstances. An outer module may mask the sus_ IPS signal for the duration of 
all operations affecting the attachment data structures, but there is only a 
limited amount of CPU time available after the signal. If sus_signal_ handler 
does not make the proper response to the Answering Service within this time, the 
process is terminated. 


The alternative strategy is to detect asynchronous detachments. This can 
be done using a half lock in the attach data. As any operation is started, the 
half lock has one added to its value. When an operation is completed, one is 
subtracted. If the detach or close entrypoints are called and find a nonzero 
half lock, they may not free any storage that may be referenced by interrupted 
operations. Instead, they set flags in the attach data indicating that an 
asynchronous close or detach has taken place. When any of the other entrypoints 
detect these bits, they assume that a new attachment has been made, and call 
iox_ on the new attachment to complete their operation. Then they return. 


For example, if tty_'s put_chars operation gets an error indicating that 
the process no longer has permission to use the terminal, it checks for the 
asynchronous bits. If they are not present, it blocks to await the arrival of 
the sus_ signal. If they are, it calls iox_$put_chars on its actual_iocb, and 
returns the results it returns. 
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SECTION 5 


REFERENCE TO COMMANDS AND SUBROUTINES BY FUNCTION 


COMMAND REPERTOIRE 


The Multics commands described in this manual are organized by function 


into the following categories: 


Debugging and Performance Monitoring Facilities 


Input/Output System Control 


Language Translators, Compilers, Assemblers, and Interpreters 


Object Segment Manipulation 


Storage System, Access Control and Rings of Protection 
Storage System, Logical Volumes 

Storage System, Mailbox Manipulation 

Storage System, Segment Manipulation 


Detailed descriptions of these commands, arranged alphabetically rather than 
functionally, are given in Section 6 of this document. In addition, many of the 


commands have online descriptions, 


which the user may obtain by invoking the 


help command (described in the MPM Commands). 


See "Reference to Commands By Function" in Section 1 of the MPM Commands 
for the functional grouping of the commands described in that manual. 


Debugging and Performance Monitoring Facilities 


area Status 

create area 

delete external variables 
display component name 
list external variables 


list temp segments 
print linkage usage 


reset external variables 
set_system_storage 


set user storage 


Signal 
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displays information about an area 

creates an area and initializes it 

deletes specified variables managed by the 
system 

converts bound segment offset into referenced 
component object segment offset 

prints information about variables managed by 
the system 

lists segments in temporary segment pool 

prints block storage usage for combined linkage 
regions 

reinitializes system managed variables 

establishes an area as the storage region for 
normal system allocations 

establishes an area as the storage region for 
normal user allocations 

Signals Multics conditions 
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Input/Output System Control 


dial_manager_call provides command interface to answering 
service's dial facility 


Language Translators, Compilers, Assemblers, and Interpreters 


alm invokes ALM assembler 
alm_abs invokes ALM assembler in absentee job 


Object Segment Manipulation 


print_bind_map prints bind map of object segment 
print_link_info prints information about object segments 


Storage System, Access Control and Rings of Protection 


set_ring brackets changes ring brackets of segment 
set_dir_ring brackets changes ring brackets of a directory 


Storage System, Logical Volumes 


delete _volume_quota deletes a quota account for a logical volume 
and is used by volume executives 


Storage System, Mailbox Manipulation 


mbx_create creates mailbox 

mbx_delete acl deletes entries from mailbox ACL 
mbx_list_acl lists ACL of mailbox 

mbx_set_acl adds and changes entries on mailbox ACL 
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Storage System, Segment Manipulation 


archive sort sorts components of archive segment 
copy_switch off turns off the copy switch of a specified 
segment 
copy _switch_on turns on the copy switch of a specified 
segment 
reorder archive orders components of archive segment 
set max length specifies maximum length of nondirectory 
~ segment 


SUBROUTINE REPERTOIRE 


The Multics subroutines described in this manual are organized by function 
into the following categories: 


Argument List Manipulation Routines 

Clock and Timer Procedures 

Command Environment Utility Procedures 

Condition Mechanism 

Data Type Conversion Procedures 

Formatted Output Facilities 

Error Handling Procedures 

Input/Output System Procedures 

Miscellaneous Procedures 

Object Segment Manipulation 

Process Synchronization 

Resource Control Package (RCP) 

Run Units 

Storage System, Access Control and Rings of Protection 
Storage System, Address Space 

Storage System, Directory and Segment Manipulation 
Storage System, Utility Procedures 


Since many subroutines can perform more than one function, they are listed 
in more than one group. 


Detailed descriptions of these subroutines, arranged alphabetically rather 
than functionally, are given in Section 7 of this document. 


Many of the functions provided by these subroutines are also available as 
part of the runtime facilities of Multics-supported programming languages; users 
are encouraged to use the language-related facilities wherever possible. 


See Section 1 of the MPM Subroutines for the functional grouping of the 
subroutines described in that manual. 


Argument List Manipulation Routines 


decode _descriptor_ extracts information from argument 
descriptors 
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get_entry_arg descs__ 


get_entry_point_dcel_ 


Clock and Timer Procedures 


timer_manager_ 


change default_wdir_ 
check_star_name_ 


ev_userid_ 


dl_handler_ 
get_default_wdir_ 
get_definition_ 
get_entry_arg descs_ 
get_entry_name_ 
get_equal_name_ 
get_system_ free area_ 
help. 

nd_handler_ 

read password_ 


requote string _ 


terminate process_ 


Condition Mechanism 


condition interpreter _ 


continue_to_ signal_ 


find_condition_frame_ 
find_condition_info_ 
hes $get_exponent_control 


hes $set_exponent_control 
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returns information about the calling 
sequence of an entry point 

returns attributes needed to construct a PL/I 
declare statement 


allows user process interruption after 
specified amount of CPU or real-time 
passes 


Command Environment Utility Procedures 


changes the user's current default working 
directory 

verifies formation of entrynames according to 
star name rules 

converts a character string containing an 
abbreviated User_id into one containing 
all three components 

issues queries for situations involving 
deletion 

returns pathname of user's current default 
working directory 

returns pointer to specified definition 
within an object segment 

returns information about the calling 
sequence of an entry point 

returns associated name of externaliy defined 
location or entry point in segment 

constructs target name by substituting from 
entryname into equal name 

returns pointer to system free area for 
calling ring 

locates info segs 

resolves name duplication 

reads user's password from the terminal 

doubles all quotes within a character string 
and returns the result enclosed in quotes 

terminates the process in which it is called 


prints formatted error message for most 
conditions 

enables on unit that cannot completely handle 
eondition to tell signalling program to 
search stack for other on units for 
condition 

returns a pointer to the most recent 
eondition frame 

returns information about condition when 
signal occurs 

returns flag settings that control handling 
of overflow and underflow conditions 

changes flag settings that control handling 
of overflow and underflow conditions 
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prepare mec restart_ 


sect manager _ 


signal 
unwinder 


Data Type Conversion Procedures 


ascii to ebedic_ 
assign 


char to numeric_ 
CV bin_ 


cv dec_ 

ev_ dec check 
ev entry_ 

ev hex_ 


ev_hex_ check_ 
ev oct 
ev_oct_ check 


ev ptr_ 
ebcdiec to ascii 
valid decimal _ 


Error Handling Procedures 


active fne err_ 


active fne err$ Suppress name 


convert Status code_ 


sub err 


Formatted Output Facilities 


dump segment _ 


Tioe 


checks machine conditions for restartability, 
and permits modifications to them for user 
changes to process execution, before 
condition handler returns 

manipulates the System Condition Table; can 
set a static handler, get a pointer to 
one, and call one 

signals occurrence of given condition 

performs nonlocal goto on Multics stack 


performs conversion from ASCII to EBCDIC 

assigns specified source value to specified 
target performing required conversion 

converts user-supplied string to a numeric type 
eonverts binary representation of integer to 
12-character ASCII string 

converts an ASCII representation of a decimal 
integer to fixed binary(35) 

Same aS cv dec except that a code is returned 
indicating the possibility of a conversion 
error 

eonverts a virtual entry to an entry value 

converts an ASCII representation of a 
hexadecimal integer to fixed binary(35) 

Same aS cv hex except that a code is returned 
indicating the possibility of a conversion 
error 

converts an ASCII representation of an octal 
integer to fixed binary(25) of an octal 
integer. 

same aS cv oct except that a code is returned 
indicating the possibility of a conversion 
error 

converts a virtual pointer to a pointer value - 

performs conversion from EBCDIC to ASCII 

ehecks decimal data for validity 


prints formatted error message and signals 
active function error condition 

prints formatted error message and signals 
active function error condition but 
suppresses name of calling function 

returns short and long status messages for 
given status code 

reports errors detected by other subroutines 


prints a dump formatted the same way as 
dump segment command 


Input/Output system Procedures 


convert _dial_message__ 
dial_manager_ 


dprint_ 


iod_info_ 


pli_io_ 


Miscellaneous Procedures 


add_epilogue_handler_ 
execute epilogue_ 


get_privileges_ 
hash_index_ 

hes $get_process_usage 
mode string 


system_info_ 


Object Segment Manipulation 


component_info_ 


object_info_ 


tssi_ 


Process Synchronization 


create ips mask_ 
get_lock_ id_ 


hes $get_ips_mask 
hes_$reset_ips_mask 


hes $set_automatic ips mask 
hes $set_ips_mask 


hes_$wakeup 


ipe_ 
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controls dialed terminals 

interfaces the answering 
facility 

adds segment print or punch request to 
specified queue 

extracts information from I/0 daemon tables 
for commands and subroutines submitting 
I/O daemon requests 

extracts information about PL/I 


service dial 


adds to execute epilogue_'s list of programs 

cleans up language I/0 buffers in conjunction 
with run units 

returns process' access privileges 

computes the value of a hash function 

retrieves system resource usage information 

Manipulates mode strings; can parse, analyze, 
and create them 

provides user with information on _ system 
parameters 


returns information similar to object_info_ 
information about a component of a bound 
segment 

prints structural and identifying information 
extracted from object segment 

Simplifies use of storage system by language 
translators 


returns a bit string that can be used to 
disable specified ips interrupts 

returns a 36-bit unique identifier to be used 
in setting locks 

returns the value of the current ips mask 

replaces the entire ips mask with a specified 
ips mask 

replaces the entire automatic ips mask with a 
specified ips mask 

replaces the entire ips mask with a specified 
ips mask 

sends interprocess communication wakeup to 
blocked process over specified event 
channel 

user interface to Multics interprocess 
communication facility 
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Resource Control Package (RCP) 


ev_rep attributes 
interpret _resource_desc_ 
resource control_ 


resource, info. 


Run Units 


run 


run_$environment_info 


aim_check_ 


eonvert_aim_attributes_ 


copy_acl_ 


cross ring 


eross ring io $allow_cross 


ev_dir_mode_ 


ev_mode_ 


get_privileges__ 

get_ring | 

hes _$add_ dir inacl entries 
hes ~$add_ inacl entries 

hes _ $delete | dir inacl entries 
hes _ $delete_ ~inacl entries 
hes $get_ dir ring | ~ brackets 
hes $get ring brackets 

hes $list dir inacl 

hes $list_inacl 

hes $replace dir_inacl 

hes _Sreplace_ inacl 

hes $set dir. ring brackets 
hes ~$set_ _ring_ brackets 
read _ allowed 

read write allowed_ 

write | allowed_ 
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manipulates RCP resource attribute 
specifications and descriptions 

displays selected contents of RCP resource 
description 

provides interface to 
control facility 

returns selected information about RCP 
resource types defined on the system 


Multies resource 


sets up special environment 
programs 


returns information about run environment 


for executing 


Storage System, Access Control and Rings of Protection 


determines relationship between two access 
attributes 

eonverts representation of process'/segment's 
access authorization/class into character 
string of defined form 

copies the ACL from one 
directory to another. 

allows an outer ring to attach to a 
preexisting switch in an inner ring and 
perform I/O operations 

allows use of an I/O switch via cross ring 
attachments from an outer ring _ 

converts a character string containing access 
modes for directories into a bit string 
used by the ACL entries 

converts a character string containing access 
modes for segments into a bit string used 
by the ACL entries 

returns process! access privileges 

returns number of current protection ring 

adds specified access modes to initial ACL 
for segments or directories 

deletes specified entries from 
for segments or directories 

returns ring brackets for specified segment 
or subdirectory 

returns all or part of 
segments or directories 

replaces initial ACL with user-provided one 
for segments or directories 

sets ring brackets for 
directory 

determines if AIM allows specified operations 
on object given process' authorization 
and object's access class 


segment, MSF, or 


initial ACL 
ACL for 


initial 


enanrt 
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Storage System, Address Space 


hes $get_search_rules 


hes  $get_ _system_ search rules 
hes $initiate search rules 


returns user's current search rules 
prints site-defined search rule keywords 
allows user to specify search rules 


Storage System, Directory and Segment Manipulation 


hes $del_ dir tree 
hes _$force_ write 
hes _$get_ author 
hes $get_be_author 


hes _$get_max_length 

hes $get_ max length_seg 
hes $get_ safety sw 

hes $get_ safety _sw_seg 
hes _$quota_move 


hes _ $quota_read 


hes_$set_entry_bound 


hes $set_entry_bound_seg 


hes $set_ max length 

hes $set_max_length_seg 
hes _$set_ _safety_ Sw 

hes $set_safety_sw_seg 
hes _$star_ 


mdc_ 


shes $set_force write limit 


Storage Systen, Utility Procedures 


area_info_ 

define area_ 
get_default_wdir_ 
get_definition_ 
get_entry_name_ 


get_equal_name_ 


hes $get_link_target 
hes $get_user_effmode 


mhes $get_seg usage 
match star_name_ 


msf_ manager _ 


release area_ 
suffixed_name_ 
tssi 
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deletes subdirectory's contents 

writes pages from memory to disk 

returns author of segment, directory, or link 

returns bit-count author of a segment or 
directory 

returns maximum length of segment in words 


returns safety switch value of directory or 


segment 

moves all or part of quota between two 
directories 

returns record quota and accounting 


information for directory 
sets entry point bound of segment 


sets maximum length of segment 
sets safety switch of segment 


returns storage system type and all names 
that match entryname according to star 
name rules 

provides entrypoints for master directory 
manipulation 

fixes limit on number of pages to be written 
to disk 


returns information about an area 

initiaiizes a region of storage as an area 

returns pathname of user's current default 
working directory 

returns pointer to specified definition 
within an object segment 

returns associated name of externally defined 
location or entry point in segment 

constructs target name by substituting from 
entryname into equal name 

returns the target pathname of a link 

returns a user's effective access mode to a 
branch 

returns the number of page faults taken ona 
segment since its creation 

compares entryname with star name 

provides the means for multisegment files to 
create, access, and delete components, 
truncate the file and control access 

cleans up an area 

aids in processing suffixed names 

Simplifies use of storage system by language 
translators 
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SECTION 6 


COMMANDS 


COMMAND DESCRIPTION FORMAT 


This section contains descriptions of Multics commands, presented in 
alphabetical order. Each description contains the name of the command 
(including the abbreviated form, if any), discusses the purpose of the command, 
and shows the correct usage. Notes and examples are included when deemed 
necessary for clarity. The discussion below briefly describes the content of 
the various divisions of the command descriptions. 


Name 


The "Name" heading lists the full command name and its abbreviated form. 
The name is usually followed by a discussion of the purpose and function of the 
command and the expected results from the invocation. 


Usage 


This part of the command description first shows a single line that 
demonssrates the proper format to use when invoking the command and then 


expletie each element in the line. The following conventions apply in the usage 
line. 


by Optional arguments are enclosed in braces (e.g., {path}, {User_ids}). 
All other arguments are required. 


2. Control arguments are identified in the usage line with a leading 
hyphen (e.g., {-control args}) simply as a reminder that all control 
arguments must be preceded by a hyphen in the actual invocation of the 
command. 


3. To indicate that a command accepts more than one of a specific 
argument, an "s" is added to the argument name (e.g., paths, {paths}, 
{-control_args}). 


NOTE: Keep in mind the difference between a plural argument name that is 
enclosed in braces (i.e., optional) and one that is not (i.e., 
required). If the plural argument is enclosed in braces, clearly no 
argument of that type need be given. However, if there are no 
braces, at least one argument of that type must be given. Thus 
"paths" in a usage line could also be written as: 

path! {path2 ... pathn} 
The convention of using "paths" rather than the above is merely a 
method of saving space. 


4, Different arguments that must be given in pairs are numbered (e.g., 
XxXX1 yyy1 {... xxxn yyyn}). 
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oe To indicate that the same generic argument must be given in pairs, the 
arguments are given letters and numbers (e.g., pathAl pathBi {... 
pathAn pathBn}). 


6. To indicate one of a group of the same arguments, an "i" is added to 
the argument name (e.g., pathi, User_idi). 
To illustrate these conventions, consider the following usage line: 


command {paths} {-control_args} 


The lines below are just a few examples of valid invocations of this command: 


command 

command path path 

command path -control arg 

command -control_arg -control arg 

command path path path -control_arg -control arg -control arg 


In many cases, the control arguments take values. For simplicity, common 
values are indicated as follows: 


STR 
any character string; individual command descriptions indicate any 
restrictions (e.g., must be chosen from specified list; must not 
exceed 136 characters). 

N 
number; individual command descriptions indicate whether it is octal 
or decimal and any other’ restrictions (e.g., cannot be greater than 
4). 

DT 
date-time character string in a form acceptable to the 
convert_date_to_binary subroutine described in the MPM Subroutines. 

path 


pathname of an entry; unless otherwise indicated, it may be either a 
relative or an absolute pathname. 


The lines below are samples of control arguments that take values: 


-access name STR, -an STR 
-ring N, -rg N 

-date DT, -dt DT 
-home_dir path, -hd path 


Notes 


Comments or clarifications that relate to the command as a whole are given 
under the "Notes" heading. Also, where applicable, the required access modes, 
the default condition (invoking the command without any arguments), and any 
Special case information are included. 
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Examples 


The examples’ show different valid invocations of the command. An 
exclamation mark (!) is printed at the beginning of each user-typed line. This 
is done only to distinguish user-typed lines from system-typed lines. The 


results of each example command line are either shown or explained. 


Other Headings 


Additional headings are used in some descriptions, particularly the more 
lengthy ones, to introduce specific subject matter. These additional headings 
may appear in place of, or in addition to, the notes. 
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Name: alm 


ALM is the standard Multics assembly language. It is commonly used for 
privileged supervisor code, higher level support operators and utility packages, 
and data bases. It is occasionally used for efficiency or for hardware features 
not accessible in higher level languages; however, its routine use is 
discouraged. 


The alm command invokes the ALM assembler to translate a segment containing 
the text of an assembly language program into a Multics standard object segment. 
A listing segment can also be produced. These segments are placed in the user's 
current working directory. 


The ALM language is described briefly in this command description. The 
Multics Processor Manual, Order No. AL39, fully describes the instruction set. 


Usage 


alm path {-control_ args} 


where: 


is path 
is the pathname of an ALM source segment that is to be translated by 
the ALM assembler. If path does not have a_ suffix of alm, one is 
assumed. However, the suffix must be the last component of the name 
of the source segment. 


es control_args 
are optional arguments that can only appear after the path argument. 
The control arguments are: 


-list, -ls 
produces an assembly listing segment. 


-no_ symbols 
Suppresses the listing of a cross-reference table in the listing 
segment. This cross-reference table is included by default in the 
listing segment when the -list control argument is given. 


-brief, -bf 
prevents errors from being printed on the terminal. Any errors are 
flagged in the listing (if one has been requested). 


~arguments STR, -ag STR 
indicates that the assembled program may expect arguments. If 
present, it must be the last control argument to the alm command and 
must be followed by at least one argument. See "Macros in ALM" 
later in this description. 


Notes 


The only result of invoking the alm command without control arguments is to 
~ Wh jec 


+ asneoman + 
Cu segmienev. 
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A  suecessful assembly produces an object segment and leaves it in the 
user's working directory. If an entry with that name existed previously in the 
directory, its access control list (ACL) is saved and given to the new copy. 
Otherwise, the user is given re access to the segment with ring brackets v,v,v 
where v is the validation level of the process that is active when the object 
segment is created. 


If the user specifies the -list control argument, the alm command creates a 
listing segment in the working directory and gives it a name consisting of the 
entryname portion of the source segment with the suffix list rather than alm 
(e.g-, a source segment named prt_conv_.alm would have a listing segment named 
prt_conv_.list). The ACL is as described for the object segment except that the 
user is given rw access to the newly created segment. Previous copies of the 
object segment and the listing segment are replaced by the new segments created 
by the compilation. 


The assembler is serially reusable and sharable, but cannot be reentered 
once translation has begun; that is, it cannot be interrupted during execution, 
invoked again, then restarted in its previous invocation. 


Error Conditions 


Errors arising in the command interface, such as inability to locate the 
source segment, are reported in the normal Multics manner. Some conditions can 
arise within the assembler that are considered malfunctions in the assembler; 
these are reported by a line printed on the terminal and also in the listing. 
Any of the above cases is immediately fatal to the translation. 


Errors detected in the source program, such as undefined symbols, are 
reported by placing one-letter error flags at the left margin of the erroneous 
line in the listing segment. Any line so flagged is also printed on the user's 
terminal, unless the -brief control argument is in effect. Flag letters and 
their meanings are given below. 


B mnemonic used belongs to obsolete (Honeywell Model 645) processor 
instruction set 


D error in macro definition or macro expansion; more detailed diagnostic 
for specific error given in listing 


E malformed expression in arithmetic field 


ny 


error in formation of pseudo-operation operand field 


reference to a multiply defined symbol 


2 


unimplemented or obsolete pseudo-operation 
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) unrecognized opcode 


i phase error; location counter at this statement has changed between 
passes, possibly due to misuse of org pseudo-operation 


R expression produces an invalid reloeation type 


S rror in the definition of a symbol 
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T undefined modifier (tag field) 
U reference to an undefined symbol 


7 digit 8 or 9 appears in an octal field 


The errors B, E, M, 0, P, and U are considered fatal. If any of them 
occurs, the standard Multics "Translation failed" error message is reported 
after completion of the translation. 


ALM Language 


An ALM source program is a sequence of statements separated by newline 
characters or semicolons. The last statement must be the end pseudo-operation. 


Fields must be separated by white space, which is defined to include space, 
tab, new page, and percent characters. 


A name is a sequence of uppercase and lowercase letters, digits, 
underscores, and periods. A name must’ begin with a letter, period, or 
underscore and cannot be longer than 31 characters. 


Labels 


Each statement can begin with any number of names, each followed 


immediately by a colon. Any such names are defined as labels, with the current 
value of the location counter. A label ona pseudo-operation that changes 


location counters or forces even alignment (such as org or its) might not refer 
to the expected location. White space is optional. It can appear before, 
after, or between labels, but not before the colon. 


Opcode 


The first field after any labels is the opcode. It can be any instruction 
mnemonic or any one of the pseudo-operations listed later in this description 
under "Pseudo-operations." The opcode can be omitted, and any labels are still 
defined. White space can appear before the opcode, but is not required. 


Operand 


Following the opcode, and separated from it by mandatory white space, is 
the operand field. For instructions, the operand defines the address, pointer 
register, and tag (modifier) of the instruction. For each pseudo-operation, the 
operand field is described under "Pseudo-~-operations" below. The operand field 
ean be omitted in an instruction. Those pseudo-operations that use their 


Pe a jee ese ee he Oe! Ke Ke | x 


ER face ee ae te ee Do tc ew th 2h o Sa BD el i Be ee Ba 
Uperdnlas Benerdity GU NOUV PermLe eno YUperalu LLicCiu LO VO YMLELLOEU. 
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Comments 


Since the assembler ignores any text following the: end of the operand 
field, this space is commonly used for comments. In those pseudo-operations 
that do not use the operand field, all text following the opcode is ignored and 
can be used for comments. Also, a quote character (") in any field introduces a 
comment that extends to the end of the statement. (The only exceptions are the 
acc, aci, and bei pseudo-operations, for which the quote character can be used 
to delimit literal character strings.) The semicolon ends a statement and 
therefore ends a comment as well. 


Instruction Operands 


The operand field of an instruction can be of several distinct formats. 
Most common is the direct specification of pointer register, address, and tag 
(modifier). This consists of three subfields, any of which can be omitted. The 
first subfield specifies a pointer register by number, user-defined name, or 
predefined, namne-(pro;.pri,- pr2s prs, pray “prs, pre, prt). The subfield ends 
with a vertical bar. If the pointer register and vertical bar are omitted, no 
pointer register is used in the instruction. The second subfield is. any 
arithmetic expression, relocatable or absolute. This is the address part of the 
instruction, and its default is zero. Arithmetic expressions are defined below 
under "Arithmetic Expressions." The last subfield is the modifier or tag. It 
is separated from the preceding subfields by a comma. If the tag subfield and 
comma are omitted, no instruction modification is used. (This is an all zero 
modifier.) Valid modifiers are defined below under "Modifiers." 


Other formats of instruction operands are used to imply pointer registers. 
If a symbolic name defined by temp, tempd, or temp8 is used in the address 
subfield (it can be used in an arithmetic expression), then pointer register 6 


is used if no pointer register is specified explicitly. This form can have a 
tag subfield. 


Similarly, if an external expression is used in the address subfield, then 
pointer register 4 is implied; this causes a reference through a link. The 
pointer register subfield may not be specified explicitly. If a modifier 
subfield is specified, it is taken as part of tne external expression; the 
instruction has an implicit n* modifier to go through the link pair. External 
expressions are defined below under "External Expressions." 


A literal operand begins with an equal sign followed by a_ literal 
expression. The literal expression can be enclosed in parentheses. It has no 
pointer register but can have a tag subfield. A literal reference normally 
causes the instruction to refer to a word in a literal pool that contains the 
value of the literal expression. However, if the modifier du or dl is used, the 
value of the literal is placed directly in the instruction address field. 
Literal expressions are defined below under "Literal Expressions." 
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Special Instruction Formats 


Certain instructions assembled by the ALM assembler do not follow the 
standard opcode-operand format as described above. These instructions fall into 
three basic classes: the repeat instructions, special treatment of the index 
and pointer register instructions, and EIS instructions. Each of these special 
cases is described below. . 


REPEAT INSTRUCTIONS 


The repeat instructions are used to repeat either one ora pair of 
instructions until specified termination conditions are met. There are _ two 
basic forms: 


rpt tally,delta,termi,term2,...,termn 


generates the machine rpt instruction as described in the Multics Processor 
Manual. Both tally and delta are absolute arithmetic expressions. The termi 
specify the termination conditions as the names of corresponding conditional 
transfer instructions. This same format can be used with the rpt, rpd, rpda, 
and rpdb pseudo-operations: 


rptx ,delta 
generates the machine rpt instruction with a bit set to indicate that the tally 


and termination conditions are to be taken from index register 0. This format 
can be used with rplx and rpdx. 


INDEX REGISTER INSTRUCTIONS 


The opcodes for manipulation of the index registers have the general form 
opxn, where n specifies the index register to be used in the operation. LM 
allows the more general form: 


opx index ,operand 


which assemblies opxn, where index is an absolute arithmetic expression whose 
value is n. This format can be used for all index register instructions. 


POINTER REGISTER INSTRUCTIONS 


As with the index register instructions, the opcodes for the manipulation 
of the pointer registers have the general form oprn, where n_ specifies the 
pointer register to be used. ALM extends this form to allow: 


opr pointer,operand 
which assembles as oprn, where n is found as follows: If pointer is a built-in 
pointer name (pr0O, pri, etc.), that register is selected; otherwise, pointer 


must be an absolute arithmetic expression whose value is n. This format can be 
used with all pointer register instructions except spri. 
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EIS MULTIWORD INSTRUCTIONS 


An EIS multiword instruction consists of an operation code word, followed 
by one or more descriptor words. The descriptor words can be assembled by using 
the desc pseudo-operations listed under "Pseudo-operations" below. The 
operation code word has the following general form: 


eisop (MF1),(MF2),keyword1(octexpression) ,keyword2 


where: 


he MF1,MFe 
are EIS modification fields as described in "EIS Modifiers" below. 


2% keyword] 
can be either fill, bool, or mask. 


3. octexpression 
is a logical expression that specifies the bits to be placed in the 
appropriate parts of the instruction. 


4, keyword2 
can be round, enablefault, or ascii; these cause single option bits 
in the instruction to be set. 


Keywords can appear in any order, before or after an MF field. This format 
ean be used for all Multics EIS multiword instructions. 


EIS SINGLEWORD 


— oe a me a ava a aru 


The Multics processor contains a set of 10 instructions that may be used to 
alter the contents of an address register. These instructions have the 
following general form: 


opcode prjioffset,modifier 


where: 

ie pr 
selects the address register that is to be modified by the 
instruction. 

agen offset 


is a value whose interpretation is dependent upon the opcode used. 


ce modifier 
must be one of the register modifiers (au, gl, x0, etc.). 


These instructions have two modes of operation depending on the setting of 
bit 29 in the instruction. If bit 29 is 1, the current contents of the selected 
address register are used in determining its new contents; if bit 29 is 0, the 
eontents of the word and bit offset portions of the selected address register 
are assumed to be zero at the start of the instruction (this results in a load 
operation into the selected address register). ALM normally sets bit 29 to 1, 
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unless the opcode ends in x (e.g., awdx is an awd instruction with bit 29 set to 
0). This format can be used with a4bd, a6bd, a9bd, abd, awd, s4bd, s6bd, sQ9bd, 
sbd, and swd. 


Examples of Instruction Statements 


Six examples of instruction statements are shown below. A. brief 
description of each example follows the sample statements. 


xlab: lda pro0j;2,* " Example 1. 
eax? xlab-1 
reel <sys_info>;j[clock_],* " Example 2. 
segref sys_info,time delta " Example 3. 
adl time _delta+1 
temp nexti " Example 4. 
1x10 nexti,* 
link goto,<unwinder_>j[unwinder_] " Example 5. 
tra pr4;jgoto,* 
ana =o777777,du " Example 6. 
ada =v36/list_end-1 


Example 1 shows direct specification of address, pointer register, and tag 
fields. In the second instruction, no pointer register is specified, and the 
Symbol xlab is not external, so no pointer register is used. 


Example 2 shows an explicit link reference. Indirection is specified for 
the link as the item at clock (in sys_info) is merely a pointer to the final 
operand. 


Example 3 uses an external expression as the operand of the adl 
instruction. In this particular case, the operand itself is in sys info. 


Example 4 uses a stack temporary. Since the word is directly addressable 
using pr6, the modifier specified is used in the instruction. 


Example 5 shows a directly specified operand that refers to an external 
entity. It is necessary in this case to specify the pointer register and 
modifier fields, unlike segref. 


Example 6 uses two literal operands. Only the second instruction causes 
the literal value to be stored in the literal pool. 
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Arithmetic Expressions 


. An arithmetic expression consists of names (other than external names) and 
decimal numbers joined by the ordinary operators + ~ *® /. Parentheses can be 
used with their normal’ meaning. 


An asterisk in an expression, when not used as an operator, has the value 
of the current location counter. 


All intermediate and final results of the expression must be absolute or 
relocatable with respect to a single location counter. A relocatable expression 
cannot be multiplied or divided. 


Logical Expressions 


A logical expression is composed of octal constants and absolute symbols 
combined with the Boolean operators + (OR), - (XOR), * (AND), and ~*~ (NOT). 
Parentheses can be used with their normal meaning. 


External Expressions 


An external expression refers symbolically to some other segment. It 
consists of an external name or explicit link reference, an optional arithmetic 
expression added or subtracted, and an optional modifier subfield. An external 
name is one defined by the segref pseudo-operation. An explicit link reference 
must begin with a segment name enclosed in angle brackets (the less-than and 
greater-than characters) and followed by a vertical bar. This can optionally be 
followed by an entryname in square brackets. For example: 


<segname>;[entryname] 
<segname>{j0,5* 


An alternative form of external expression must begin with a segment name 
followed by a dollar sign. This may be followed by an entryname, an arithmetic 
expression, or a modifier, all of which are optional. For example: 


segname$ 


segname$entr yname-1 
Segname$+3,5 


A segment name of *text, *link, or *static indicates a reference to this 
procedure's text, linkage, or static sections. 


A segment name of *system indicates a reference to the external variable 
(or common block) entryname, which is managed by the linker. 


A link pair is constructed for each combination of segment name, entryname, 
arithmetic expression, and tag that is referenced. 
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Literal Expressions 


A literal reference causes the instruction to refer to a word in a literal 
pool that contains the value specified. However, the du and dl modifiers cause 
the value to be stored directly in the address field of the instruction. The 
literal pool is allocated in the text section. The various formats of literals 
are described in the following paragraphs. 


A decimal literal can be signed. If it contains a decimal point or 
exponent, it is floating point. If the exponent begins with "d" instead of "e", 
it is double precision. A binary scale factor beginning with "b" indicates 
fixed point and forces conversion from floating point. The binary point ina 
literal with a binary scale factor is positioned to the right of the bit 
indicated by a decimal integer following the "b". 


An octal literal begins with an "o" followed by up to 12 octal digits. 


ASCII literals can occur in two forms. One form begins with a decimal 
number between 1 and 32 followed by "a" followed by the number of data 
characters specified by the integer preceding the "a", which can cross statement 
delimiters. The other form begins with "a" followed by up to four data 
characters, which can be delimited by the newline character. 


A GBCD literal begins with "h" followed by up to six data characters, which 
can be delimited by the newline character. Translation is performed to the 
6-bit character code. 


An ITS (ITP) literal begins with "its" ("itp") followed by a parenthesized 
list containing the same operands accepted by the its (itp) pseudo-operation. 
The value is the same as that created by the pseudo-operation. 


A variable-fieid iiterai begins with “v" followed by any number of decimal, 
octal, and ASCII subfields as in the vfd pseudo-operation. It must be enclosed 
in parentheses if a modifier subfield is to be used. 


If a variable-field literal, octal literal, or fixed point literal (decimal 
literals with a "b" binary scale factor) is used with du or dl modification, 
then the lower 18 bits of the literal are placed in the address field of the 
instruction. If any other type of literal is used with du or dl modification, 
then the upper 18 bits of the literal are placed in the address field of the 
instruction. 
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Modifiers 


These specify indirection, index register address modification, immediate 
operands, and miscellaneous tally word operations. They can be specified as 
2-digit octal numbers (particularly useful for instructions like stba) or 
symbolically using the mnemonics described here. 


Simple register modification is specified by using any of the register 
designators listed below. It causes the contents of the selected register to be 
added to the effective address. 
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Designators Register 

xO 0 index register 0 

x1 1 index register 1 

x2 2 index register 2 

X3 3 index register 3 

x4 4 index register 4 

x5 5 index register 5 

x6 6 index register 6 

x7 7 index register 7 

n none (no modification) 

au A bits 0-17 

al A bits 18-35 or 0-35 
qu Q bits 0-17 

ql Q bits 18-35 or 0-35 
ic instruction counter 


In addition to the above, any symbol that is not otherwise a valid modifier 
(e.g., au, ql, x7) may be used as a modifier to designate an index 
register. Thus, 


equ rege, 3 
lda sp}0,*rege 


is equivalent to: 


lda spi0,*3 


Register-then-indirect modification is specified by using any of the 
register designators followed by an asterisk. If the asterisk is used alone, it 
is equivalent to the n* modifier. The register is added to the effective 
address, then the address and modifier fields of the word addressed are used in 
determining the final effective address. Indirect cycles continue as long as 
the indirect words contain an indirect modifier. 


Indirect-then-register modification is specified by placing an asterisk 
before any one of the register designators listed above. 


Direct modifiers are du and dl. They cause an immediate operand word to be 
fabricated from the address field of the instruction. For dl, the 18 address 
bits are right-justified in the effective operand word; for du they are 
left-justified. In either case, the remaining 18 bits of the effective operand 
are filled with O's. 


Segment addressing modifiers are its and itp; they can only occur in an 
indirect word pair ona double-word boundary. The addressing modifier its 
causes the address field of the even word to replace the segment number of the 
effective address, then continues the indirect cycle with the odd word of the 
pair. Nearly all indirection in Multics uses ITS pairs. For itp, see the 
Multics Processor Manual. 


Tally modifiers i, ci, se, scr, ad, sd, id, di, ide, and die control 
incrementing and decrementing of the address and tally fields in the indirect 
word. They are difficult to use in Multics because the indirect word and the 
data must be in the same Segment. 
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Fault tag modifiers f1, f2, and f3 cause distinct hardware faults whenever 
they are encountered. The modifier f2 is reserved for use in the Multics 
dynamic linking mechanism; the other modifiers result in the signalling of the 
conditions fault_tag_1 and fault _tag 3. 


EIS Modifiers 


An EIS modifier appears in the first word of an EIS multiword instruction. 
It affects the interpretation of operand descriptors in subsequent words of the 
instruction. No check is made by ALM to determine whether the modifier 
specified is consistent with the operand descriptor specified elsewhere. 


An EIS modifier consists of one or more subfields separated by commas. 
Each subfield contains either a keyword as listed below, a register designator, 
or a logical expression. The values of the subfields are OR'ed together to 
produce the result. 


Keyword Meaning 

pr Descriptor contains a pointer register reference. 

id Descriptor is an indirect word pointing to the true 
descriptor. 

rl Descriptor length field names a register containing data 
length. 

xN Descriptor address is offset by the value in index register 


N (N can be 0 - 7, as above). 


Separate Static Object Segments 


If a separate static object segment is desired, a join pseudo-operation 
specifying static should exist in the program. 


Pseudo-operations 


The pseudo-operations are listed below in alphabetical order. Additional 
pseudo-operations are provided by the macro facility. See "Macros in ALM" 
(following this list of pseudo-operations) for a further description of their 
syntax. 


ace /string/,expression 

assembles the ASCII string <string> into as many contiguous words as 
are required (up to 42). The delimiting character (/ above) can be 
any character other than white space. The quoted string can contain 
newline and semicolon characters. The length of the string is placed 
in the first character position in ace format. If present, expression 
defines the length of the string; otherwise, the length is the actual 
length of the quoted string. If the given string is shorter than the 
defined length, it is padded on the right with blanks. If it is 
longer, it will be truncated to the defined length. 
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aci 


acy 


arg 


bei 


bfs 


bool 


bss 


call 


dec 


alm 


/string/,expression 
is similar to ace, but no length is’ stored. The first character 
position contains the first character in aci format. 


/string/,expression 

is similar to aci, but only the rightmost four bits of each ASCII 
character are stored into the corresponding character position of a 
string of 4-bit characters. If the given string is shorter than the 
defined length, it is padded on the right with zeros. 


operand 
assembles exactly like an instruction with a zero opcode. Any form of 
instruction operand can be used. 


/string/,expression 
is similar to aci, but uses GBCD 6-bit character codes and GBCD blanks 
for padding. 


name ,expression 
reserves a block of expression words with name defined as the address 
of the first word after the block reserved. 


name,expression 
defines the symbol name with the logical value expression. See the 
definition of logical expressions above under “Logical Expressions." 


name,expression 
defines the symbol name as the address of a block of expression words 
at the current location. The name can be omitted, in which case the 
Storage is still reserved. 


routine(arglist) 
calls out to the procedure routine using the argument list at arglist. 
Both routine and arglist can be any valid instruction operand, 


including tags. If arglist and the parentheses are omitted, an empty 
argument list is created. All registers are saved and restored by 


call. 


number 1,number2,...,numbern 
assembles the decimal integers numberi, number2, through numbern into 
consecutive words. 


desc4a address(offset) ,length 
desc6a address(offset),length 
desc9a address(offset),length 


generates one of the operand descriptors of an EIS multiword 
instruction. The address is any arithmetic expression, possibly 
preceded by a pointer register subfield as in an instruction operand. 
The offset is an absolute arithmetic expression giving the offset (in 
characters) to the first bit of data. It can be omitted if the 
parentheses are also omitted. The length is either a built-in index 
register name (al, au, ql, x0, ete.) or an absolute arithmetic 
expression for the data length field of the descriptor. The character 
size (in bits) is specified as part of the pseudo-operation name. 
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descHfl 
desc4ils 
desc4ns 
desc4ts 


address(offset),length,scale 
address(offset),length,scale 
address(offset),length,scale 
address(offset),length,scale 


alm 


generates an operand descriptor for a decimal string. The scale is an 


absolute arithmetic expression for 


applied to the operand. It can 
floating-point operand. Data 
pseudo-operation name: desc4fl 


indicates leading 


digits 


desc9ts. 


deseb address(offset),length 


generates an operand descriptor for a 


length are in bits. 


dup expression 
duplicates all source statements following the statement containing 


the 
containing 


This value 


dup pseudo-operation up to 
the dupend pseudo-operation. 
statements are duplicated is equal to 
must be positive and nonzero. 


be nested. 


dupend 


a decimal scaling factor to be 

omitted, and is ignored ina 
format is specified in the 
indicates floating point, desc4ls 
sign fixed point, desc4ns indicates unsigned fixed 
point, and desc4ts indicates trailing 
can be specified by using desc9fl, desc9ls, desc9ns, and 


Sign fixed point. Nine-bit 


bit string. Both offset and 


(but not including) the statement 


The number of times that the 
the value of the expression. 
Also, dup statements may not 


terminates the range of a dup pseudo-operation. 


eight 


(see the even pseudo-operation) 


end 


terminates the source segment. 


entry namel,name2,...,namen 


generates entry 


sequences for labels namel, name2, through namen and 


makes the externally-defined symbols namei, name2, through namen refer 
to the entry sequence code rather than directly to the labeis. fhe 


entry sequence 
pr4 


external symbolic references 
entry sequence can use (alter) 


and 7, and the A andQ registers. 
properly set (as they normally are). 


entrybound 


places the current value of the 
entrybound field. 


performs such functions as initializing base register 
to point to the linkage section, 
(link, segref, explicit links). The 
base register pr2, index registers 0 
It requires pr6 and pr7 to be 


which is necessary to make 


location counter in the object_map 
If more than one such operation is encountered, the 


last one is effective. See the gate macros.incl.alm include file for 


an example of this operation's use. 
of the object segment's directory 


Note that setting the entry bound 
entry is still necessary. See 


hes _$set_entry_bound for a description of that operation. 
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equ name,expression 
defines the symbol name with the arithmetic value expression. 


even 
inserts padding (nop) to a specified word boundary. 


firstref extexpression1(extexpression2) 
ealls the procedure extexpression! with the argument pointer 


extexpression2 the first time (in a process) that this object segment 
is linked to by an external symbol. If extexpression2 and the 
parentheses are omitted, an empty argument list is supplied. The 
expressions are any external expressions, including tags. 


7/81 6-16. 1 AK92C 


THIS PAGE INTENTIONALLY LEFT BLANK 


7/81 AK92C 


alm 


alm 


getlp 
sets the pointer register pr4 to point to the linkage section. This 
ean be used with segdef to simulate the effect of entry. This 
operator can use pointer register pr2, index registers 0 and 7, and 
the A and Q registers, and requires pr6 and pr7 to be set properly. 


include segmentname 
inserts the text of the segment segmentname. inel. alm immediately after 
this statement. The "translator" search list, which has the synonym 
"trans," is used to locate the segment (see the search facility 
commands in MPM Commands). 


Inhibit oft: 
instruct assembler to turn off the interrupt inhibit bit in subsequent 
instructions. This mode continues until the inhibit on 
pseudo-operation is used. 


inhibit on 
instructs assembler to turn on the interrupt inhibit bit (bit 28) in 
Subsequent instructions. This mode continues until the inhibit off 
pseudo-operation is used. 


itp prno,offset,tag 
generates an ITP pointer referencing the pointer register prno. 


its segno,offset,tag 
generates an ITS pointer to the segment segno, word offset <offset>, 
with optional modifier tag. If the current’ location is not even, a 
word of padding (nop) is inserted. Such padding causes any iabdels on 
the statement to be incorrectly defined. 


join /text/namel,name2,.../link/name3,name4,.../static/name5,name6,.... 

appends the location counters namel, name2, etc., to the text section, 
appends the location counters name3, name4, ete., to the linkage 
section and appends the location counters name5, name6, etc., to the 
Static section. Any number of names can appear. Each name must have 
been previously referred to in a use statement. Any location counters 
not joined are appended to the text section. If both link and static 
are specified in join pseudo-operations, then a warning is printed on 
the terminal. 


link name,extexpression 
defines the symbol name with the value equal to the offset from lp to 
the link pair generated for the external expression extexpression. An 
external expression can include a tag subfield. The name is not an 
external symbol, so an instruction should refer to this link by: 
pr4jiname,* 


maclist keyword {save} 
indicates how listing of statements ainepares by macro expansion is to 
be done. The following keywords are accepted: 


oft 
suppresses the listing of macro-generated statements and object 
code 
on 
lists such statements and their associated object code 
object 
lists only the object code 
restore 


reverts the macro listing mode to a previously saved setting 
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The save argument, if present, saves the current macro listing ina 
pushdown stack. The default macro listing mode is on. 


macro name 


12/79 


indicates the start of amacro definition. When a macro name is 
defined, it may then be used as a pseudo-operation to trigger the 
expansion of the macro. See "Macros in ALM" below for a complete 
description of the definition and expansion of macros in ALM. 


mod <expression> 
inserts padding (nop) to an <expression> word boundary. 


name objectname 
specifies again the object segment name as it appears in the object 
segment. By default, the storage system name is used. 


null 

is ignored. This pseudo-operation is used for comments. 
oct number! ,number2,...,numbern 

is like dec, with octal integer constants. 
odd 


(see the even pseudo-operation) 


org expression 
sets the location counter to the value of the absolute arithmetic 
expression <expression>. The expression can only use symbols 
previously defined. 


perprocess static 
turns on the object segment's perprocess static switch. See the 
description of the run command in the MPM Commands for an explanation 
of perprocess static. 


push expression 
creates a new stack frame for this procedure, containing expression 
words. If expression is omitted (the usual case), the frame is just 
large enough to contain all celis reserved py temp, tempd, and temps. 


rem 
(see the null pseudo-operation) 


return 
is used to return from a procedure that has performed a push. 


segdef namel,name2,...,namen 
makes the labels namel, name2, through namen available to the linker 
for referencing from outside programs, using the symbolic names namel, 


name2, through namen. Such incoming references go directly to the 
labels namei, name2 through namen so the segdef pseudo-operation is 
usually used for defining external static data. For program entry 


points, the entry pseudo-operation is usually used. 


segref segname,namel ,name2,...,namen 
defines the symbols namei, name2, through namen as external symbols 
referencing the entry points name1, name2, through namen in segment 
segname. This defines a symbol with an implicit base register 
reference. 
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set name,expression 
assigns the arithmetic value expression to the symbol name. Its value 


ean be reset in other set statements. 


short call routine 


calls out to routine using the argument list pointed to by prO. Only 
pr4 and pr6 are preserved by short_call. 
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short_return 
is used to return from a procedure that has not performed a push. 


sixtyfour 
(see the even pseudo-cperation) 


temp name1(n1),name2(n2),...,namen(nn) 
defines the symbols name?, name2, through namen to reference unique 
stack temporaries of n1, n2, through nn words each. Each ni is an 
absolute arithmetic expression and can be omitted (the parentheses 
should also be omitted). The default is one word per namei. 


temp8 namei(n1),name2(n2),...,namen(nn) 
is similar to temp, except that 8-word units are allocated, each on an 
8-word boundary. 


tempd name1(n1),name2(n2),...,namen(nn) 
is similar to temp, except that ni (n2 through nn) double words are 
allocated, each on a double-word boundary. 


use name 
assembles subsequent code into the location counter name. The default 
location counter is ".text.". 


vfd T1L1/expression1,T2L2/expression2,...,ITnLn/expressionn | 

is variable format data. Each expressioni is of type Ti and is stored 
in the next Li bits of storage. As many words are used as required. 
Individual items can cross word boundaries and exceed 36 bits in 
length. Type is indicated by the letters "a" (ASCII constant) or "o" 
(logical expression) or none (arithmetic expression). Regardless of 
type, the low-order Li bits of data are used, padded if needed on the 
left. The Ti can appear either before or after Li. 


Restrictions: The total length of the variable format data cannot 
exceed 128 words. A relocatable expression cannot be stored ina 
field less than 18 bits long, and it must end on either bit!17 or 
bit!35 of a word. 


zero expressioni,expression2 
assembles expression! into the left 18 bits of a word and expression2 
into the right 18 bits. Both subfields default to zero. 


Macros in ALM 


The ALM macro facility provides a means for defining and using sequences of 
text to be inserted at various points in an ALM program. Each such sequence of 
text, called amacro, is defined by the use of the macro pseudo-operation in 
ALM. A macro definition consists of all text following the line containing the 
macro pseudo-operation until the character string, &end. The sequence of text 


is named by the symbol appearing as the operand to the macro pseudo-operation. 


At any point in a program subsequent to the definition of a macro, the 
macre name can be used aS a pseudc-operation in ALM. Whenever it is so0 used, 
ALM inserts the text sequence defined as that macro. 


The macro facility is purely text manipulative. It deals with macro 
definitions as a continuous stream of text characters interspersed with control 
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The macro facility is purely text manipulative. It deals with macro 
definitions as a continuous stream of text characters interspersed with control 
sequences. Each control sequence begins with the & character. The control 
sequence, &end, terminates the macro definition. When a macro is invoked by 
using its name as a pseudo-operation, the macro definition is scanned from left 
to right. All text between control sequences is copied, and variable 
information is inserted in place of the control sequences. The resulting macro 
expansion is presented to ALM for assembly. 


Macros may be given arguments by placing operands in fields corresponding 
to the operands of a pseudo-operation. These arguments can be substituted into 
the expanded copy of the macro as specified by various control sequences within 
the macro definition. Control sequences are also provided to facilitate 
iteration, conditional text selection, unique symbol generation, and other 
operations. 


The macro facility also provides a set of special pseudo-operations that 
are distinct from the regular ALM pseudo-operations. These special 
pseudo-operations allow for the conditional assembly of source lines and the 
printing of messages to the user's terminal during assembly. The argument 
Syntax of these pseudo-operations is the same as that of macros, not the 
expressions and symbols of the ALM assembler. 


Contents of a Macro 


The body of a macro (i.e., the text starting on the line following the 
macro pseudo-operation and ending just before the character string &end) can 
include any text and control sequences which, when expanded, yield valid ALM 
source code. The body of a macro can include invocations of other macros and 
even the definition of other macros. 


Macro definitions are shown in the assembly listing with their internal 
line numbers to the left of the ALM source line number. (These internal numbers 
are used in diagnostics produced by the macro expander.) Macros may be 
redefined, the later definition replacing the earlier. Macros may also redefine 
all existing ALM operations and pseudo-operations. | 


An example macro is given below: 


macro move_a_to b 


lda a 
sta b 
&end 


Invoking a Macro 


A macro is invoked by specifying its name as a pseudo-operation. Arguments 
to the macro can appear in the variable field separated by commas. A comment 
may follow the argument list, separated from it by white space or a double 
quote. Arguments to macros that include spaces, tabs, newline characters, 
commas, or semicolons must be enclosed in matching parentheses. The parentheses 
are stripped from the argument during macro expansion. The use of parentheses 
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a line with a comma. Leading white space preceding the continuation of the 
argument list on the next line is ignored. 


Code and statements produced by the macro facility are placed in the 
assembly listing without source line numbers. Symbols used by a macro expansion 
appear in the cross-reference listing as though they were referenced on the line 
of the macro invocation. The listing of statements produced by macro expansion 
may be controlled through the use of the maclist pseudo-operation. See the 
description under "Pseudo-operations" above. 


Restrictions 


Any macro definition that begins in an include file must end in that 
include file. 


A macro must be defined before it is expanded. It can appear before its 
definition within another macro definition, but that other macro may not be 
expanded until the macro it invokes is defined. 


Macros may be invoked in code produced by macro expansions. The depth of 
such recursion, however, must not exceed the current limit of 100. 


Control Sequences 


Character substitutions and conditional expansions at the time of macro 
expansion are effected by the control sequences detailed below. The use of any 
ampersand followed by any sequence not defined below is noted by ALM as an 
assembly error. 


1. &0, &1, &2 
the character & followed immediately by any positive decimal integer 
(< 100) is replaced, upon expansion, with the corresponding argument 
passed to the macro (see "Notes" and "Examples" below). 


The special sequence &0 causes a reference to a unique label at the 
start of the macro expansion. The label is generated only if the &0 
sequence is generated within a macro. 


2. &u 
is expanded to be a unique character string of the form ...00000, 
---00001, etc., that is different from any other such strings 
expanded with &u control. 

3. &p 
is expanded to be the same string as the previous &u expansion. 

H. = 6&n 


is expanded to be the same string as the next &u expansion. 
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ae 


alin 


10. 


11. 


T2. 


13. 


14. 


15. 


16. 


17. 


&U 


&i 


&An 


&K 


&k 


&ln 


&& 


&Fn 
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is expanded to be a unique character string of the form .._ 00000, 
-- 00001; however, multiple occurrences of &U within the same macro 
yield the same string. 


indicates the beginning of an iteration sequence. The text 
following the &(n and up to but not including the next &) is 
expanded repeatedly (see "Iteration" below). 


is expanded to the particular element of the iteration set for which 
the current iteration is being performed (see "Iteration" below). 


is expanded into the decimal integer corresponding to the relative 
position of the particular element of the iteration set over which 
the current iteration is being performed. 


is expanded to be the nth argument following the -ag or -arguments 
control argument to the alm command. 


is expanded as a decimal number equal to the number of arguments in 
the current macro invocation. 


is expanded as a decimal number equal to the number of elements in 
the current iteration set. 


is expanded as a decimal number equal to the length in characters of 
the nth argument in the current macro invocation. 


is expanded to a Single & character. This facilitates macro 
definitions within macro expansions. 


expands to a string constructed by concatenating all arguments to 
the macro invocation, from the nth onward, separated by commas. If 
n is not given, 1 is assumed. 


&Fqn or &FQn 


&fn 


is Similar to &Fn, except that each argument is enclosed in 
parentheses as it is concatenated to the expanded string. This 
control sequence should be used when sublists of macro arguments are 
to be passed to other macros and there is a possibility that some of 
these arguments may contain white space, newline characters, etc. 


is similar to &Fn, except that the elements of the current iteration 
set are concatenated. 


&fqn or &fQn 


is similar to &Fqn and &FQn, except that the elements of the current 
iteration set are enclosed in parentheses. 
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23. 


24. 
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&Rm,n 

is used to cause iteration over the arguments in a macro invocation, 
as opposed to the iteration elements of a single macro argument. 
The use of &R affects the operation of the next &( control sequence. 
The m is a decimal number equal to the number of the first argument 
to be selected; n is a decimal number equal to the number of the 
last argument to be selected. If n is missing or zero, it is 
assumed to be equal to the number of arguments in the macro 
invocation. If mis missing or zero, it is assumed to be 1 (see 
"Notes" below). 


&[ 

marks the start of a selection group. The text following the &[ and 
up to but not including the matching &] is expanded conditionally. 
The elements of a selection group are separated by the control 
sequence & . Each element can contain other selection groups to a 
nesting depth of 10. When a macro is expanded, only one element of 
a selection group is used. This element is chosen by a control 
Seguence preceding the &[ control sequence. 


&sn 

~ Selects the nth element of the following selection group. All 
expanded text between the &s and &[ control sequences is interpreted 
as the decimal number n. If n is zero or greater than the number of 
elements in the selection group, no element is selected. 


ail expanded text between the &= and the next &[ control sequence is 
broken into two character strings. If no comma is found in the 
expanded text, c2 is taken to be a null string. If the two strings 
are equal, by character string comparison, the first element of the 
following selection group is used. Otherwise, the second element, 
if present, is used. 


&*=e1,¢2 
—"=Fhe &*= control sequence is identical to the &= control sequence, 
except that the first element is selected if the strings are 
unequal, and the second, if present, is selected if they are equal. 


&<nT,n2 
&>=n1,n2 
&<=n1,n2 
~ ~€hese control sequences are similar to the &= and &*= control 
sequences, except that the expanded text between this control 
sequence and the next &[ control sequence is interpreted as. two 
decimal integers. If no comma is found, n2 is taken to be zero. An 
arithmetic comparison of the numbers is performed, as specified by 
the particular control sequence used. A result of true causes the 
first element of the following selection group to be used. A result 
of false causes the second element, if present, to be used. 


&end 
Signifies the end of the macro definition. The statement containing 
the &end control sequence is not part of the macro body, and hence, 
is not included as part of the macro definition. 
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Notes 


Decimal numbers’ produced by &K, &k, and &x are generated with no leading 
blanks or zeros. The number zero is generated as the single digit 0. 


Numeric arguments to &n, &(n, &Fn, &fn, &Fqn, &fqn, and &An can be 
comprised of from zero to three digits. TheSe numbers must appear as such in 
the unexpanded macro definition. If numeric text is to follow one of the above 
control sequences, all three digits of n must be supplied. 


The numbers used by &Rm,n, as well as the strings and numbers used by the 
relational and selection control sequences can be of any length. They appear in 
the expanded text and need not necessarily be in the macro definition. These 
expanded strings and numbers are, of course, not placed in the final macro 
expansion being generated. 


If a given macro argument is not specified in a particular invocation of 
that macro, a null character string is used for that argument during macro 
expansion. 


Iteration 


The macro facility provides the ability to map the expansion of a subset of 
a macro definition over a set of elements, expanding that part of the definition 
repeatedly, selectively Substituting each element of the iteration set in turn. 
By means of this technique, lists may be processed. 


An iteration set consists of elements separated by commas. It has the same 
syntax as the argument list of a macro invocation, including conventions on the 
use of parentheses for quoting and continuation via the trailing comma. Two 
types of iteration sets may be referenced in a macro expansion: 


Te The argument list to a macro invocation itself may be used as an 
iteration set, in which case the arguments of the macro invocation are 
the elements. This type of iteration set is specified by means of the 
&R control sequence. 


2. Any argument to a macro invocation may be used as an iteration set, if 
it, internally, has the same syntax as an argument list to a macro 
invocation. This type of iteration set is specified when &R is not 
used. 


The text between the sequences &( and &) is expanded once for each element 
in the iteration set, in left to right order. If the second form of iteration 
set is used, the number of the argument to the macro invocation may appear (one 
to three digits, no digits are mapped into 1) immediately after the &( sequence. 
Any occurrence of the sequence &i between the sequences &( and &) is replaced by 
the current element of the iteration set. The sequence &x is replaced by the 
decimal number of the relative position of that element in the iteration set 
(not the argument number, in the first type of iteration set). 
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Iterations may not be nested. Any iteration that starts in an element of a 
selection group must end in that element of a selection group. No iteration may 
end in any element of a selection group unless it started in that element of 
that selection group. 


Macro Facility Pseudo-Operations 


The macro facility provides a set of pseudo-operations in addition to the 
macro pseudo-operation already described. These pseudo-operations are different 
from the other pseudo-operations provided by the assembler insofar as the syntax 
of their arguments, which is the syntax of macro invocation arguments, with all 
quoting and continuation conventions of them, and not the syntax of other 
pseudo-operation arguments to the assembler. 


The use of these pseudo-operations, like all other ALM pseudo~operations, 
is not limited to code produced by macro expansion. They can be placed anywhere 
in source segments and include files, as well as in macro code, but the 
conditional pseudo-operations can not be nested. 


es warn 
prints out its first argument on the user's terminal, preceded by 
the string "ALM assembly:" and followed by a newline character. 
This argument, without the prefix, is also placed in the program 
listing. 


the character strings that are the first and second arguments to ife 
are compared. If they are the same character string, all assembler 
statements between the one containing the end of the argument list 
to ife, and the next one containing the string ifend in any context 
at all are assembled. No part of the line containing the string 
ifend is assembled. If the first and second arguments are not 
equal, none of these lines are assembled. 


3% ine 
the same as ife, but assembly of the text up to ifend proceeds only 
if the first two arguments are not equal by character string 
comparison. 


4, ifint 

the first argument to the ifint pseudo-operation is inspected to see 
if it is a valid decimal integer. If so, all assembler statements 
between the one containing the end of the argument list to ifint and 
the next one containing the string ifend in any context at all are 
assembled. No part of the line containing the ifend is assembled. 
If the first argument to ifint is not a valid integer, none of these 
lines are assembled. 


5. inint 


the same as ifint, but assembly of the text up to ifend proceeds 
only if the first argument is not a valid decimal integer. 
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all of the arguments to the alm command following the -ag or 
“arguments control argument are inspected, and compared with the 
first argument to ifarg. If any of these command arguments compare 
equal, by character string comparison, to the first argument to 
ifarg, all assembler statements between the one containing the end 
of the argument list to ifarg and the first one containing the 
String ifend in any context at all are assembled. No part of the 
line containing the ifend is assembled. If the first argument to 
ifarg does not appear among’ the arguments following -ag or 
~arguments, none of these lines are assembled. 


ie inarg 
the same as ifarg, but assembly of the text up to ifend proceeds 
only if the first argument to inarg is not found among the arguments 
to the alm command following -ag or -arguments. 


In all of the conditional constructs above, the key string, ifend, must 
appear in the same source segment or macro expansion as the statement containing 
the conditional pseudo-operation. If the ifend key string appears in the 
ifend_exit string, and the entire construct appears in a macro expansion, and 
the predicate of the conditional construct is met (i.e., the statements are 
being assembled, not skipped), the assembler ceases to take input from that 
macro expansion, aS though the last statement in that macro expansion had been 
assembled. 


Examples 


The following macro definitions show typical expansions: 


macro load 
1d&1 &2 
&end 


might be used as follows: 
load x0,temp ldx90 temp 
or: 


load a,(spi3,*) lda spi3,* 


The use of parentheses in the second example causes the comma to be ignored as a 
parameter delimiter. The macro definition: 


macro test 

lda &1 

tpl &U 

Sta last_minus 
&U sta &2 

&end 


might be used as follows: 


test a,b lda a 
tpl --« 00000 
sta last_minus 
~+ 00000: sta b 
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The following example shows how iteration is used. 


macro 
& R& ( vfd 
&) 

& end 


might be used as follows: 


el: table 


The following 
macro definition: 


macro 
lda 
ife 
aos 
ifend 
&end 


might be used as follows: 


4464 6410 


example shows 


table 
18/&1,18/&0 


vfd 
vfd 
vfd 
vid 


how 


meter 

&1 

&2,0n 
meterword,al 


meter foo,on lda 
aos 
Tne following macro shows how &x might be used. The 
macro callm 
&(3 eppbp &i 
spribp &24+&x¥2 
&) 
eaq 2*&X-2 
lls 36 
staq &2 
eall &1(&2) 
é&end 
might be used as follows: 
callm sys,arg,(=1,(=14aError from 
yielding: 
_eppbp =1 
spribp arg+1%2 
eppbp =14aError from “d. 
spribp arg+2*2 
eaq 2t4-2 
lls 36 
staq arg 
eall sys(arg) 
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The macro definition: 


18/4,18/e1 
18/6,18/e1 
18/8,18/e1 
18/10, 18/e1 


can be used. The 


foo 
meterword ,al 


macro definition: 


“d.)) 
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The following macro definition shows how conditional expansion might be 


used: 
macro tab9 
&R&(&=&x, 1&[ vfd &;,&]09/&i&) 
&end 
This macro might be invoked as follows: 
tab9 16,42,13,36,67 


expanding to: 


vfd 09/16,09/42,09/13,09/36,09/67 


The following example shows how macros may be defined by macros, and 


used 


to powerful: effect. These macros allow a call like a PL/I call to be generated, 


with descriptors. 


The following macro is invoked to declare variables by specifying their 


address, data type, and precision: 


macro declare 

macro del &1 

eppo &2 

epp1 =v1/1,6/&3,17/0, 12/&4 
&&end 

&end 


This macro may be invoked as follows: 


declare count,buffer+2,fixed,17 
or: 


declare progname, (lp; xlink,*) ,char, 32 


These macro invocations cause the following macro definitions to 
produced: 


macro del count 

eppod buf fer+2 

epp1 =v1/1,6/fixed,17/0,12/17 
éend 

macro del progname 

eppo lpixlink,* 

epp1 =v1/1,6/char,17/0, 12/32 
&end 


Assume that at some point in the assembly the statements: 


equ char ,21 
equ fixed,1 


defining the PL/I descriptor types for these data types appear. 


be 


AK92 


The following macro definition, when 


with descriptors. Assume that the statement: 


tempd 


argl(16) 


appears at some point in the progran. 


macro 

&R2&( del &i 
spriod 
sprii 

&) 
ldaq 
staq 
call 
é&end 


gcall 


argl+2*&x 
ar gl+2*&K-2+2*&x 


=v18/2*&K-2 ,18/0,18/2*&K-2 ,18/4 
argl 
ai Carel) 


When the following macro invocation is issued: 


gcall program, count, progname 


the following expansion is immediately produced: 


del count 
sprio 
sprit 


argl+2*j 
argl+2*3-2+2*1 


dcl_ progname 


spriod 
spril 


ldaq 
staq 
call 


This is further expanded when 
to: 


2pp0 
eppl 
sprio 
spril 
eppd 


argl+2*3-2 
argl1+2*35-2+2*2 


=v18/2*3-2,18/0,18/2*3-2,18/4 
argl 
program(argl1) 


alm 


invoked, generates a full PL/I call 


the dcl_count and dcl_progname macros are expanded 


buffer+2 
=vi/1,6/fixed,17/0,12/17 
argl+2*1 

arg1+2*3-2+2*'} 

lp; xlink,* 


=v1/1,6/char,17/0,12/32 
argl+2*2 

argl+2*3-2+2*2 
=v18/2*3-2,18/0,18/2*3-2,18/4 
argl 


program(argl) 


which is precisely the code required for a full PL/I call. 
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Name: alm_abs, aa 


The alm_abs command submits an absentee request to perform ALM assemblies. 
The absentee process for which alm_abs submits a request assembles the segments 
named and dprints and deletes each listing segment if it exists. If the 
-output_ file control argument is not specified, an output segment, path.absout, 
is created in the user's working directory. (If more than one path is 
specified, the first is used.) If the segment to be assembled cannot be found, 
no absentee request is submitted. 


Usage 


alm_abs paths {alm_arg} {-dp_ args} i-control_args} 


where: 
1. paths 

are pathnames of segments to be assembled. 
2. alm_arg 


can be the -list control argument accepted by the alm command 
(described earlier in this document). 


3. dp_args 
can be one or more control arguments (except -delete) accepted by 
the dprint command. (See the MPM Commands for a description of the 
dprint command.) 


4, control args 
can be one or more of the following control arguments: 


-queue N, -q N 
is the priority queue of the request. The default queue is defined 
by the system administrator. See "Notes" for a description of the 
interaction with the dprinting of listing files. 


-hold 


specifies that alm_abs should not dprint or delete the listing 
segment. 


-limit N, -li N 
places a limit on the CPU time used by the absentee process. The 
parameter N must be a_ positive decimal integer specifying the limit 
in seconds. The default limit is defined by the site for each 
queue. An upper limit is defined by the site for each queue on each 
shift. Jobs with limits exceeding the upper limit for the current 
shift are deferred to a shift with a higher limit. 


-output_file path, -of path 


specifies that absentee output is to go to segment path where path 
is a pathname. 
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Notes 


Control arguments and segment pathnames can be mixed freely and can appear 
anywhere on the command line after the command. All control arguments apply to 
all segment pathnames. If an unrecognizable control argument is’ given, the 
absentee request is not submitted. 


Unpredictable results can occur if two absentee requests are submitted that 
could simultaneously attempt to assemble the same segment or write into the same 
absout segment. 


When performing several assemblies, it is more efficient to give several 
segment pathnames in one command rather than several commands. With one 
command, only one process is set up. The links that need to be snapped when 
setting up a process and when invoking the assembler need be snapped only once. 


If the -queue control argument is not specified, the request is submitted 
into the default absentee priority queue defined by the site and, if requested 
(via -list), the listing files are dprinted in the default queue of the request 
type specified on the command line (via dp args). (If no request type is 
specified, the "printer" request type is used.) 


If requested (via -list) when the -queue control argument is specified, the 
listing files are dprinted in the same queue as is used for the absentee 
request. If the request type specified for dprinting (via dp args) does not 
have that queue, the highest-numbered (i.e., the lowest priority) queue 
available for the request type is used and a warning is issued. 
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Name: archive sort, as 


The archive sort command is used to sort the components of an archive 
segment. The components are sorted into ascending order by name using the 
standard ASCII collating sequence. The original archive segment is replaced by 
the sorted archive. For more information on archives and reordering them, see 
the archive command in the MPM Commands and the reorder archive command in this 
document. a 


Usage 


archive sort paths 


where paths are the pathnames of the archive segments to be sorted. The user 
need not supply the archive suffix. 


Notes 


There may be no more than 1000 components in an archive segment that is to 
be sorted. 


Storage system errors encountered while attempting to move the temporary 
sorted copy of the archive segment back into the user's original segment result 
in diagnostic messages and preservation of the sorted copy in the user's process 
directory. If the original archive segment is protected, the user is 
interrogated to determine whether it should be overwritten. 
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Name: area_ Status 


The area status command is used to display certain information about an 
area. 


Usage 
area_Status virtual ptr {-control_args} 


where: 

1. virtual ptr 
is a virtual pointer to the area to be looked at. The syntax of 
virtual pointers is described in the cv_ptr_ subroutine description. 


2. control args 
can be chosen from the following: 


-trace 
displays a trace of all free and used blocks in the area. 


-long, -lg 
dumps the contents of each block in both octal and. ASCII format. 


Note 


If the area has internal format errors, these are reported. The command 
does not report anything about (old) buddy system areas except that the area is 
in an obsolete format. 
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The copy names command description, formerly on this page, has been moved to the 
MPM Commands and Active Functions manual, Order No. AG9e. 


re ee 
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Name: copy switch off, esf 


This command turns off the copy switch of specified segments. 


Usage 


copy switch off paths 


where paths are the pathnames of segments. 


Notes 
The current state of a segment's copy switch can be determined by issuing 
the command: 


status path -copy switch 


This command replaces the resetcopysw command. 
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Name: copy switch _on, csn 


This command turns on the copy switch of specified segments. 


Usage 


copy _switch_on paths 


where paths are the pathnames of segments. 


Note 


This command replaces the setcopysw command. 
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Name: create area 


The create area command creates an area and initializes it with 
user-specified area management control information. 


Usage 


create area virtual ptr {-control_args} 


where: 


1. virtual ptr 
Ts a virtual pointer to the area to be created. The syntax of 
virtual pointers is described in the cv_ptr_ subroutine description. 
If the segment already exists, the specified portion is still 
initialized as an area. 


2% control _ args 
can be chosen from the following: 


~no_ freeing 
allows the area management mechanism to use a faster allocation 
Strategy that never frees. ; 


~dont free 
- 


1s used during debugging to disable the free mechanism. This does 
not affect the allocation strategy. 


alitaa 
GLive 
tructs the area management mechanism to clear blocks at 
ocation time. 


-zero_on free 
instructs the area management mechanism to clear blocks at free 
time. 


-extend 
causes the area to be extensible, i.é€., Span more than one segment. 
This feature should be used only for perprocess, temporary areas. 


-Size N 
specifies the octal size, in words, of the area being created or of 
the first component, if extensible. If this control argument is 
omitted, the default size of the area is the maximum size allowable 
for a segment. The minimum area if forty octal words. 


-id STR 


specifies a string to be used in constructing the names. of the 
components of extensible areas. 
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j Name: delete external variables, dev 


The delete external variables command deletes from the user's name space 
specified variables managed by the system for the user. All links to those 
variables are unsnapped and their storage is freed. 


Usage 
delete external variables names {-control arg} 


where: 


1. names 


are the names of the external variables, separated by spaces, to be 
deleted. 


2. control arg 


Ts -unlabeled common (or -uc) to indicate unlabeled (or blank) 
common. 


4/80 6-36 AK92B 


The delete volume quota command, formerly on this page, has been moved to the # 
Multies Administrators' Manual Project, Order No. AK51. 
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Name: dial manager _call 


The dial _manager_call command provides a command interface to the answering 
service's dial facility. All functions which are available through the 
dial manager subroutine interface are available through this command. See the 
description of dial_manager_ for a more complete description of these functions. 


Usage 
dial_manager_call request {STR1 {STR2} {STR3}} 


where: 


La request 
maps into a call to an identically named entry in dial manager . 
Each request requires the use of a particular STR which is listed in 
the request description. A request must be one of the following: 


allow dials STR, ad STR 
requests that the answering service establish a dial line to allow 
terminals to dial to the calling process. STR must be a 
dial_ qualifier as described below. 


dial_out STR1 STR2 {STR3}, do STR1 STR2 {STR3} 
requests that an auto call channel be dialed to a given telephone 
number and, if the channel is successfully dialed, that the channel 
be assigned to the requesting process. STR1 must be a channel name 
and STR2 must be a dial out destination as described below. STR3, 
which can be omitted, is a reservation string as described below. ~ 


privileged attach STR, pa STR 
allows a privileged process to attach any terminal that is in the 
channel master file, and is not already in use. See the description 
of dial manager $privileged attach for information on what access is 
required. The effect is as if that terminal had dialed to the 
requesting process. STR must be a channel name as described below. 


registered server STR, rs STR 
requests that the answering service allow terminals to dial the 
calling process using only the dial qualifier. STR must bea 
dial _quaiifier as described below. 


release channel STR, re STR 
requests the answering service to release the channel specified by 
channel _ name. This channel must be dialed to the caller at the time 
of the request. If the channel was dialed, the channel is returned 
to the answering service and another access request may be issued. 
If the channel is a slave channel, the channel is hung up. STR must 
be a channel_name as described below. 


release channel no_hangup STR, renh STR 
is the same as release channel except that this request does not 
hang up slave channels. STR must be a channel name as described 
below. 
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‘release dial id STR, rdi STR 
informs the answering service that the user process wishes to 
prevent further dial connections, but that existing connections 
should be kept. Any connections kept can be released later with the 
release channel request. STR must be a dial qualifier as described 
below. 


shutoff dials STR, sd STR 
informs the answering service that the user process’ wishes to 
prevent further dial connections, and that existing connections 
should be terminated. STR must be a dial qualifier as described 
below. 


start_report, start 
turns on the reporting feature. See "Notes" below. STR is not used 
with this request. 


stop report, stop 
turns off the reporting feature. See "Notes" below. STR is not 
used with this request. 


terminate __ dial out STR, tdo STR 
requests that the answering service hang up an auto call line and 
unassign it from the requesting process. STR must be a channel name 
as described below. a 
2. STR 

depends on the request. STR is selected from the following list. 
(For details on the interpretation of the following qualifiers, see 
the description of the dial _manager_subroutine in this manual.) 


channel name 
is the name of a tty_channel. 


dial_ qualifier 
is the name for which the user is to be a dial server. 


dial_out_ destination 
“is the destination (e.g., phone number) of up to 32 characters. 


reservation string 
is a dial_manager_ reservation string of up to.256 characters. 


Notes 


The dial_manager_call command establishes an event call channel for 
communication with the answer ing service. This event channel and its handler 
(which is an entry point in dial _Manager_call) remain active after the command 
terminates. Any events which happen subsequent to the command termination, such 
as channel hang-ups, dial-ups, and dial requests will be decoded using 
convert _dial_ message and reported on the user_output I/0 switch when they 
happen. This reporting feature may be turned on and off by using the 
Start _report and stop_report requests. The default is on. 
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Name: display component name, den 


The display component name command converts an offset within a bound segment 
CO48%4 bound zilch {23017) into an offset within the referenced component object 
(e.g., comp!1527). This command is especially useful when it is necessary to 
convert an offset within a bound segment (as displayed by a stack trace) into an 
offset corresponding to a compilation listing. 


Usage 
display component name path offsets 


where: 

1. path 
is the pathname of a bound object segment, or an octal segment number. 
A pathname that looks like an octal segment number can be specified 
by -name nnn. 

2a offsets 


are octal offsets within the text of the bound object segment specified 
by the path argument. 


Example 


The command line: 
display component name bound zilch 17523 64251 
might respond with the following lines: 
17523 component5!1057 
64251 component7 i632 
If bound zilch were known with segment number 532, the following command 


would generate the Same output: 


den 532 17523 64251 
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Name: list external variables, lev 


The list external variables command prints information about variables 
managed by the system for the user, including FORTRAN common and PL/I external 
Static variables whose names do not contain dollar’ signs. The default 
information is the location and size of each specified variable. 


Usage 
list_external variables names {-control args} 


where: 


1. names 
are names of external variables, separated by spaces. 


2. control args 
ean be chosen from the following: 


-unlabeled common, -uc 
is the name for unlabeled (or blank) common. 


-long, -lg 
prints how and when the variables were allocated. 


-all, -a 
prints information for each variable the system is man 


-no header, -nhe 
~ suppresses the header. 
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Name: list temp segments 


The list_temp_segments command lists the segments currently in the 
temporary segment pool associated with the user's process. This pool is managed 
“by the get temp segments. and release _temp_ segments subroutines (described in 
the MPM Subroutines). 


Usage 
list_temp_segments {names} {-control_arg} 


where: 


Me names 
is a list of names identifying the programs whose temp segments are 
to be listed. Cannot be used with -all. 


2. control_arg 
is -all (or -a) to list all temporary segments, including free ones. 
If the command is issued with no arguments (the default invocation), 


it lists only those temporary segments currently assigned to 
programs (i.e., free temporary segments are not listed). 


Examples 


To list all the segments currently in the pool, type: 
! list_temp_ segments -all 
5 Segments, 2 Free 
!BBBCdfghgffkkkl.temp.0246 work 
!BBBCdffddfdffkl.temp.0247 work 
!BBBCddffdfffhhh.temp.0253 (free) 
!BBBCdgdgfhfgfsf.temp.0254 (free) 
!BBBCvdvfgvdgvvv.temp.0321 editor 
To list the segments currently in use, type: 
! list temp segments 
3 Segments 
!BBBCdfghgffkkkl.temp.0246 work 


!BBBCdffddfdffkl.temp.0247 work 
!BBBCvdvfgvdgvvv.temp.0321 editor 
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To list segments used by the program named editor, type: 
! list _temp_segments editor 
1 segment 


!BBBCvdvfgvdgvvv.temp.0321 editor 
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The mbx_add_name command, formerly described on page 6-40, is obsolete and 
has been deleted. Use instead the add_name command described in the 
MPM Commands manual. 
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Name: mbx_create, mbcr 


The mbx_create command creates a mailbox with a specified name ina 
specified directory. 


Usage 
mbx_create paths 


where paths are the pathnames of mailboxes to be created. 


Notes 
If pathi does not have the mbx suffix, one is assumed. 


The user must have modify and append permission on the directory in which 
he is creating the mailbox. 


If the creation of a mailbox would introduce a duplication of names within 
the directory, and if the old mailbox has only one name, the user is 
interrogated as to whether he wishes the old mailbox to be deleted. If the user 
answers "no", no action is taken. If the old mailbox has multiple names, the 
conflicting name is removed and a message to that effect is issued to the user. 


The extended access placed on a new mailbox is: 


adrosw user who created the mailbox 
as * .SysDaemon.* 
aow ¥ ,% ,% 


For more information on extended access, see the mail command in the MPM 
Commands and mbx_set_acl in this document. 


Example 


The command line: 
mber Green Jones.home >udd>Multics>Gillis>Gillis 


creates the mailboxes Green.mbx and Jones.home.mbx in the working directory and 
creates the maiibox Gillis.mbx in the directory >udd>Multics>Gillis. 
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has been deleted. Use instead the delete command described in the MPM Commands 
manual. 
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Name: mbx_ delete acl, mbda 


The mbx delete acl command deletes entries from tne access control list 
(ACL) of a given mailbox. 


Usage 


mbx_ delete _acl path {access names} 


where: 
8 

Ae path 
is the pathname of a mailbox. The star convention is allowed. 

eae access names 

“are access control names of the form Person id.Project id.tag. If 

all three components are present, the ACL entry with That name is 
deleted. If one or more components is missing, all ACL entries with 
matching names are deleted. (The matching strategy is described 
below under "Notes.") If no access control name is specified, the 
user's Person_id and current Project_id are assumed. 

Notes 


If path does not have the mbx suffix, one is assumed. 
The .user must have modify permission on the containing directory. 


ACL entries for *.SysDaemon.* and *.*.* cannot be deleted. Instead, this 
command sets their extended access to null. The command line "mbda path *.*,#" 
has the same effect as the command line "mbsa path null *.*.#", 


The matching strategy for access control names is as follows: 

Nie A literal component name, including "*", matches only a component of 
the same name. 

Bis A missing component name not delimited by a period is taken 


t a 
literal "*" (e.g., "*.Multics" is treated as "*.Multics.*"). Missing 
components on the left must be delimited by periods. 


ie] 
vw 


3. A missing component name delimited by a period matches any component 
name. 
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mbx_ delete acl mbx delete acl 


Some examples of access names and which ACL entries they match are: 


ee oF matches only the ACL entry "*,#,#", 


Multics matches only the ACL entry "Multics.*.*", (The absence of a 
leading period makes Multics the first component.) 


-Multics. matches every ACL entry with middle component of Multics. 
ao matches every ACL entry. 
° matches every ACL entry with a last component of "#", 


he (null string) matches every entry ending in ",*,*", 


Example 


The command line: 

mbda Green .Multics Jones 
deletes from the ACL of the mailbox Green.mbx all entries whose name ends in 
".Multics.*" and the specific entry "Jones.*.*". If no ACL entries exist for 


one of the specified access names (e.g., ending in ".Multics.*" from above 
example), an error message is printed. 
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The mbx_delete name command, formerly described on page 6-45, is obsolete 
and has been deleted. Use instead the delete name command described in the 
MPM Commands manual. 
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mbx_ list_acl mbx_ list _acl 


Name: mbx_ list acl, mbla 


The mbx_list_acl command lists all or part of the access control list (ACL) 
of a given mailbox. 


Usage 
mbx_ list _acl path {access_ names} 


where: 


1s path 
is the pathname of a mailbox. The star convention is allowed. 


ee access names 

“are access control names of the form Person_id.Project_id.tag. If 
all three components are present, the ACL entry with that name is 
listed. If one or more components is missing, all ACL entries with 
matching names are listed. The matching strategy is described under 
"Notes" in the description of the mbx_delete_acl command in this 
document. If no access control name is specified, or if the access 
control name is -all or -a, the entire ACL is listed. 


Note 


If path does not have the mbx suffix, one is assumed. 


Example 


The command line: 
mbla Green *.*.*® Jones Gillis.. 
lists, from the ACL of Green.mbx, the specific entries "*,.*.*" and "Jones.*.#" 


and all entries with a first component of Gillis. If no ACL entry with a first 
component of Gillis exists, an error message is printed. 


7/81 6-48 AK92C 


The mbx rename, mbx safety switch off, and mbx safety switch on commands, 
formerly described on pages 6-47 through 6-49, are obsolete arid have been 
deleted. Use instead the rename, switch off, and switch_on commands described 
in the MPM Commands manual. 
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mbx_set_acl mbx_set_acl 


Name: mbx_set_acl, mbsa 


The mbx.set_acl command changes and adds entries to the access control list 
(ACL) of a given mailbox. 


Usage 
mbx_set_acl path mode {access name1 ... moden} access_namen 


wheres: 


1. path 
is the pathname of a mailbox. The star convention is allowed. 


2. modei 
~ is a valid access mode. It can consist of any or all of the letters 
adrosw (see "Notes" below) or it can be "n", "null" or "" to specify 
null access. 


3. access namei 

is an access control name of the form Person id.Project id.tag. If 
all three components are present, the ACL entry with That name is 
changed; if no entry with that name exists, one is added. If one or 
more components is missing, ali ACL entries with names that match 
the access control name are changed. The matching strategy is 
described under "Notes" in the description of the mbx_delete_acl 
command in this document. If no access control name is specified, 
the user's Person_id and current Project_id are assumed. 


Notes 
If path does not have the mbx suffix, one is assumed. 
The user must have modify permission on the containing directory. 


Access on a newly created mailbox is automatically set to adrosw for the 
user who created it, asw for *.SysDaemon.*, and aow for *.*.*. The extended 
access modes for mailboxes are: 


add a add a message 


delete d delete any message 


read r read any message 
own fe) read or delete only your own messages; that is, those sent by 
you 
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mbx_set_acl mbx set acl 


Status s find out how many messages are in the mailbox 


wakeup w can send a wakeup indicating that a message was added ta the 
mailbox 


Example 


The command line: 

mbsa Green adrosw Klein.. null Jones.Multics a *.*.*# 
manipulates the ACL of Green.mbx so that all previously existing entries with a 
first component of Klein have adrosw access, Jones.Multics.* has null access and 


*,.%,® has "a" access. If no ACL entry exists with a first component of Klein, 
an error message is printed. 
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The mbx_set_max_length command, formerly described on page 6-52, is 
obsolete and has been deleted. Use instead the set_max length command described 
later in this section. 
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The move names command description has been moved to the MPM Commands 
manual. 
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The perprocess static sw_off command is obsolete and has been deleted. Use 
instead the switch off command described in the MPM Commands manual. 
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The perprocess static _sw_on command is obsolete and has been deleted. Use 
instead the switch _on command described in the MPM Commands manual. 
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print bind map print bind map 


Name: print bind map, pbm 


The print bind map command displays all or part of the bind map of an 
object segment generated by version number 4 or subsequent versions of the binder. 


Usage 
print bind map path {components} {-control_ args} 


where: 


Vs path 
is the pathname of a bound object segment. 


2e components 

are the optional names of one or more components of this bound object 
and/or the bindfile name. Only the lines corresponding to these 
components are displayed. A.component name must contain one or more 
nonnumeric characters. If it is purely numerical, it is assumed to 
be an octal offset within the bound segment and the lines corresponding 
to the component residing at that offset are displayed. A numerical 
component name can be specified by preceding it with the -name control 
argument (see below). If no component names are specified, the entire 
bind map is displayed. 


ce control args 
may be chosen from the following list: 


-long, -lg 
prints the components' relocation values (also printed in the default 
brief mode), compilation times, and source languages. 


-name STR, -nm STR 
is used to indicate that STR is really a component name, even though 
it appears to be an octal offset. 


-no header, -nhe 
~ omits all headers, printing only lines concerning the components 
themselves. 


~page offset, -pgofs 
causes the page number of the first word of the text section of each 
component to be printed as an octal number, which is the format used 
by the cumulative page trace command. If the component crosses at 
least one page boundary, a "+" character follows the page number. 
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ee 


print link _info print _link info 


Name: print link info, pli 


The print link info command prints selected items of information for the 
specified object segments. The archive component (::}) convention is accepted. 


Usage 


print link info paths {-control args} 


where: 
1. paths 
are the pathnames of object segments. 
2. control args 
@an be chosen from the following list. (See "Note" below.) 
-length, -ln 
print only the lengths of the sections in pathi. 
-entry, -et 
print only a listing of the pathi external definitions, giving their 
symbolic names and their relative addresses within the segment. 
-link, -1k 
print only an alphabetically sorted listing of all the external symbols 
referenced by pathi. 
-long 
prints more information when the header is printed. Additional 
information includes a listing of source programs used to generate 
the object segment, the contents of the "comment" field of the symbol 
header (often containing compiler options), and any unusual values 
in the symbol header. 
~header, -he 
prints the header (The header is not printed by default, if the 
-length, -entry, or -link control argument is specified.) 
-no header 
~ suppresses printing of the header. 
Note 


Control arguments can appear anywhere on the command line and apply to all 
pathnames. 
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print _link_info print _link_info 


Example 


! print _link_info program -long -length 


program 07/30/76 1554.2 edt Fri 


Object Segment >udd>Work>Wilson>program 

Created on 07/30/76 0010.1 edt Fri 

by Wilson.Work.a 

using Experimental PL/I Compiler of Thursday, July 26, 1976 at 21:38 


. Translator: PL/I 
Comment: map table optimize 
Source: 


07/30/76 0010.1 edt Fri >user dir dir>work>Wilson>s>s>program.pl1 

12/15/75 1338.1 edt Mon >library dir_dir>include>linkdel.inel.pli 

06/30/75 1657.7 edt Mon >library dir _dir>include>object info.inel.pl1 
10/06/72 1206.8 edt Fri >library dir dir>include>source map.inel.pl1 
05/18/72 1512.4 edt Thu >library dir dir>include>symbol block.inel.pl1 
01/17/73 1551.4 edt Wed >library dir _dir>inelude>pl1_symbol_block.inel.p1l1 


Attributes: relocatable,procedure,standard 

Object Text Defs Link Symb Static 
Start 0 0 3450 3620 3656 3630 
Length 11110 3450 150 36 5215 0 
<ready> 


Also printed is: 


Severity, if it is nonzero. 
Entrybound, if it is nonzero. 


Text Boundary, if it is not 2. 
Static Boundary, if it is not 2. 
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print linkage usage print linkage usage 


Name: print linkage usage, plu 


The print linkage usage command lists the locations and size of linkage and 
static sections allocated for the current ring. This information is useful for 
debugging purposes or for analysis of how a process uses its linkage segments. 


A linkage section is associated with every procedure segment and every data 
segment that has definitions. 


Usage 


print_linkage_ usage 


Note 


For standard procedure segments, the information printed includes the name 
of the segment, its segment number, the offset of its linkage section, and the 
size (in words) of both its linkage section and its internal static storage. 
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reorder archive reorder archive 


Name: preorder archive, ra 


The reorder_archive command provides a convenient way of reordering the 
contents of an archive segment, eliminating the need to extract, order, and 
replace the entire contents of an archive. This command places specified 
components at the beginning of the archive, leaving any unspecified components 
in their original order at the end of the archive. For information on archives 
and how they can be sorted, see the archive command in the MPM Commands and the 
archive sort command in this document. 


Usage 


reorder_archive {-control_argi} pathi ... {-control_argn} pathn 


where: 
hy control _argi 
may be chosen from the following: 

-console input, -ci : 
indicates the command is to be driven from terminal input. (This is 
the default.) 

-file input, -fi 
indicates the command is to be driven from a driving list. (See 
"Notes" below.) 

2s pathi 
is the pathname of the archive segment to be reordered. If pathi 
does not have the archive suffix, one is assumed. 

Notes 


If no control arguments are specified, the -console input control argument 
is assumed. 


When the command is invoked with the -console input control argument or 
with no control arguments, the message "input for archive name" is printed where 
archive name is the name of the archive segment to be reordered. Component 
names are then typed in the order desired, separated by linefeeds. A period (.) 
on a line by itself terminates input. The two-character line ".*" causes the 
command to print an asterisk (*). This feature can be used to make sure there 
are no typing errors before typing a period (.). The two-character line ".q" 
causes the command to terminate without reordering the archive. 


The driving list (-file_input control argument) must have the name 
name.order where name.archive is the name of the archive segment to be 
reordered. The order segment must be in the working directory. It consists of 
a list of component names in the order desired, separated by linefeeds. No 
period (.) is necessary to terminate the list. Any errors in the list (name not 
found in the archive segment, name duplication) cause the command to terminate 
Without altering the archive. 
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reorder archive reorder archive 


A temporary Segment named ra_temp_.archive is created in the user's process 
directory. This temporary segment is created once per process, and is truncated 
after it is copied into the directory specified by pathi. If the command cannot 
copy the temporary segment, it attempts to save it and rename it with the name 
of the archive specified. 


The reorder_archive command does not operate upon archive’ segments 
containing more than 1000 components. 
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reset external variables reset external variables 


i Name: reset external variables, rev 


The reset_external variables command reinitializes system-managed variables 
to the values they had when they were allocated. 


Usage 


reset external variables names {-control arg} 


where: 

1 names 
are the names of the external variables, separated by spaces, to be 
reinitialized. 

es control arg 
is -unlabeled common (or -uc) to indicate unlabeled (or block) 
common. 

Note 


A variable cannot be reset if the segment containing the initialization 
information is terminated after the variable is allocated. 
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set_dir_ ring brackets set _dir_ring brackets 


Name: set _dir_ ring brackets, sdrb 


The set dir ring brackets command allows a user to modify the ring brackets 
of a specified directory. 


Usage 


set dir ring brackets path {rbi {rb2}} 


where: 

Le path 
is the relative or absolute pathname of the directory whose ring 
brackets are to be modified. 

2. ring numbers 
are the numbers that represent’ the directory ring brackets 
CPDT 3. fb2)'. The ring brackets must be in the allowable range v 
through 7 (where v depends upon the user's current validation level) 
and must have the ordering: 

rb1 < rb2 
If rb1 and rb2 are omitted, they are set to the user's current 
validation level. 
rb1 
is the number to be used for the first ring bracket of the 
directory. If rb1 is omitted, rb2 cannot be given and _rb1 and rbe 
are set to the user's current validation level. 
rb2 

is the number to be used for the second ring bracket of the 
directory. 

Note 


The user's process must have a validation level less than or equal to rbi. 
See the MPM Reference Guide for a discussion of ring brackets and validation 
levels. 


12/79 6-62.1 AK92A 


set_max_length set_max_length 


Name: set_max_length, sml 


The set_max_length command allows the maximum length of a nondirectory 
segment to be set. The maximum length is the maximum size the segment can 
attain. Currently, maximum length must be a multiple of 1024 words (one page). 


Usage 


set_max_length path length {-control args} 


where: 

1 path 
is the pathname of the segment whose maximum length is to be set. 
If path is a link, the maximum length of the target segment of the 
link is set. The star convention can be used. 

26 length 


is the new maximum length expressed in words. If this length is not 
a multiple of 1024 words, it is converted to the next higher 
multiple of 1024 words. 


3. control args 
can be chosen from the following list of control arguments and can 
appear in any position: 


-decimal, -de 
says that length is a decimal number. (This is the default.) 


-octal, -oc 
Says that length is an octal number. 


-brief, -bf 
Suppresses a warning message that the length argument has been 
converted to the next multiple of 1024 words. 


Notes 


If the new maximum length is less than the current length of the segment, 
the user is asked if the segment should be truncated to the maximum length. If 
the user answers "yes", the truncation takes place and the maximum length of the 
segment is set. If the user answers "no", no action is taken. 


The user must have modify permission on the directory containing the 
segment in order to change its maximum length. 
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set_max_length set_max_length 


Examples 


The command line: 

set_max_length Resort -oc 10000 
sets the maximum length of the segment named report in the working directory to 
four pages. 

The command line: 

set_max_length *.archive 16384 


sets the maximum length of all two-component segments with a second component of 
archive in the working directory to 16 pages. 
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set_ring brackets set_ring brackets 


Name: set_ring brackets, srb 


The set_ring brackets command allows a user to modify the ring brackets of 
a specified segment. 


Usage 


set_ring brackets path {ring numbers} 


where: 
‘Ns path 
is the relative or absolute pathname of the segment whoSe ring 
brackets are to be modified. 
an ring numbers 
are the numbers that represent the three ring brackets (rb1 rb2 rb3) 
of the segment. The ring brackets must be in the allowable range 0 
through 7 and must have the ordering: 
rbi < rbe BS rb3 
If rb1, rb2, and rb3 are omitted, they are set to the user's current 
validation level. 
rb 
is the number to be used as the first ring bracket of the segment. 
If rb1 is omitted, rb2 and rb3 cannot be given and rb1, rbd, and rb3 
are set to the user's current vaiidation ievel. 
rb2 
is the number to be used as the second ring bracket of the segment. 
If rb2 is omitted, rb3 cannot be given and is’ set, by default, to 
POT. 
rb3 
is the number to be used as the third ring bracket of the segment. 
If rb3 is omitted, it is set to rbe. 
Note 
The user's process must have a validation level less than or equal to rbi. 
Ring brackets and validation levels are discussed in "Intraprocess Access 
Control" in Section 6 of the MPM Reference Guide. 
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set system storage set_system_storage 


Name: set system storage 


The set system storage command establishes an area as the storage region in 
which normal system allocations are performed. 


Usage 


set_system storage {virtual ptr}{-control arg} 


where: 

1. virtual ptr 
is a virtual pointer to an initialized area. The syntax of virtual 
pointers is described in the cv_ptr_ subroutine description. This 
argument must be specified -only if the -system control argument is 
not supplied. 

2 control arg 


can be one of the following: 


-system 

to specify the area 
-create 

to create 


process directory. 


These control arguments must be 


Notes 


To initialize 
create area command. 


or create 


The area must be set up as 


It is recommended that the 


12/79 


(and initialize) a 


used for linkage sections 


System free segment in the user's 


specified only if virtual ptr is not specified. 


an area, refer to the description of the 


either zero _on free or zero _on alloc. 


area specified be extensible. 
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set system storage set system storage 


Examples 


The command line: 

set system storage free $free_ 
places objects in the segment whose reference name is free_ at the offset whose 
entry point name is free. 

The command line: 

set_system_ storage my_seg$ 
uses the segment whose reference name is my seg. The area is assumed to be at 
an offset of O in the segment. The segment must already exist with the 
reference name my seg and must be initialized as an area. 

The command line: 


set system storage my seg 


uses the segment whose (relative) pathname is my seg. The segment must already 
exist. 
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set_user_ storage set _user_ storage 


Name: set_user_storage 


The set _user_ storage command establishes an area as the storage region in 
which normal user allocations are performed. These allocations include FORTRAN 
common blocks and PL/I external variables whose names do not contain dollar 
signs. 


Usage 


set_user_ storage {virtual ptr}{-control arg} 


where: 

1. virtual ptr 
is a virtual pointer to an initialized area. The syntax of virtual 
pointers is described in the cv_ptr_ subroutine description. This 
argument must be specified only if the -system control argument is 
not specified. 

2s control arg 


may be one of the following: 


-system 
to specify the area used for linkage sections. 


-create 
to create (and initialize) a system free segment in the user's 
process directory. 


These control arguments must be specified only if virtual ptr is not specified. 


Notes 


To initialize or create an area, refer to the description of the 
create area command. 


The area must be set up as either zero on free or zero on alloc. 


It is recommended that the area specified be extensible. 
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set_user_ storage set_user_ storage 


Examples 


The command line: 

set_user_storage free $free_ 
places objects in the segment whose reference name is free _ at the offset whose 
entry point name is free. 

The command line: 

set_user storage my seg$ 
uses the segment whose reference name is my seg. The area is assumed to be at 
an offset of Oin the segment. The segment must already exist with the 
reference name my seg and must be initialized as an area. 

The command line: 

set_user_ storage my seg 


uses the segment whose (relative) pathname is my seg. The segment must already 
exist. 
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signal . signal 


Name: signal 


The signal command signals Multics conditions, allowing the user to specify 
some information to be associated with the condition. The result of a condition 
signal depends on the user or system program handling the condition signal. 


The descriptions that follow assume that the signal is handled by the 
default unclaimed signal handler, default error handler $wall. Any messages 
described are sent over the error output switch. 


Usage 
signal CONDITION NAME {-control args} 


where: 


te CONDITION NAME 
is the name of the condition to signal. It can not contain embedded 
white space, because condition names are only significant to the 
first space character. It can not be longer than 256 characters. 


2. control args 
can be chosen from the following: 


-info string INFO MESSAGE 
associates the string INFO MESSAGE with this signal. If an error 
message is printed, this string is also printed. It must be 
enclosed in quotes if it contains whitespace or special characters. 
The string can not be longer than 256 characters. 


-code ET CODE NAME 

associates the error table code name ET CODE NAME with this signal. 
It must be a virtual pointer to an error table acceptabe to ev ptr 
If the segment name portion of the virtual pointer is omitted, 
error table is assumed. The text message defined for this error 
table code is printed if an error message is printed. Thus an 
ET CODE NAME of noentry will be interpreted as error table$noentry, 
not as a pointer to noentry!0. i 


-cant restart 
Sets the cant restart flag for this signal. The default handler 
establishes a new listener level after printing a message, and 
refuses to accept the "start" command. See "Notes" for a 
description of the default action. . 


-default restart 
sets the default restart flag for this signal. The default handler 
prints a messages and restarts execution. 


-quiet restart 


sets the quiet restart flag for this signal. The default handler 
restarts execution without printing a message. 
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signal signal 


-support signal 
sets the support signal flag for this signal. This indicates that 
the error is being signalled on behalf of another procedure, and 
should only be used when a user handler is present on the stack that 
expects it. 


Notes 


This command should not be used with any of the system conditions defined 
in the MPM Reference Guide, or with PL/I language conditions. These conditions 
require other associated information that cannot be specified with this command. 
As a result, the use of this command with these conditions may produce 
unpredictable results. 


The on command can be used to handle signals produced with this command. 


The default handler handles all condition signals that are otherwise 
unhandled by user or system programs on the stack. If neither of 
-~quiet restart, -cant restart, or -default restart are given, the default 
handler prints the error message described below, and establishes a new listener 
level. If the user types "start" at this point, execution continues. In 
particular, if the command is executed in an exec com, and the user types start, 
execution continues with the next command in the exec com. 


The default message printed for a condition signalled is of the form: 
Error: CONDITION NAME condition by signal$signal}|octalnumber 

ERROR TABLE MESSAGE 

INFO STRING MESSAGE 


If -info string is not given, the INFO STRING MESSAGE line is omitted. If -code 
is not given, the ERROR TABLE MESSAGE Tine is omitted. 
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SECTION 7 


SUBROUTINE DESCRIPTIONS 


This section contains descriptions of Multics subroutines, presented in 
alphabetical order. Each description contains the name of the subroutine, 
discusses the purpose of the subroutine, lists the entry points, and describes 
the correct usage for each entry point. Notes and examples are included when 
deemed necessary for clarity. The discussion below briefly describes the 
context of the various divisions of the subroutine descriptions. 


Name 


The "Name" heading shows the acceptabie name by which the subroutine is 
called. The name is usually followed by a discussion of the purpose and 
funetion of the subroutine and the results that may be expected from calling it. 


Entry 


Each "Entry" heading lists an entry point of the subroutine call. This 
heading may or may not appear in a Subroutine description; its use is entirely 
dependent upon the purpose and function of the individual subroutine. 


Usage 


This part of the subroutine description first shows the proper format to 
use when calling the subroutine and then explains each element of the call. 
Generally, the format is shown in two parts: a declare statement that gives the 
arguments in PL/I notation and a call line that gives an example of correct 
usage. Each argument of the call line is then explained. Arguments can be 
assumed to be required unless otherwise specified. Arguments that must be 
defined before calling the subroutine are identified as Input; those arguments 
defined by the subroutine are identified as Output. 


Comments or clarifications that relate to the subroutine as a whole (or to 
an entry point) are given under the "Notes" heading. 
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Other Headings 


Additional headings are used in some descriptions, particularly the more 
lengthy ones, to introduce specific subject matter. These additional headings 
may appear in place of, or in addition to, the notes. 


Status Codes 


The standard status codes returned by the subroutines are further 
identified, when appropriate, as either storage system or I/O system. For 
convenience, the most often encountered codes are listed in Appendix B of the 
MPM Subroutines. They are divided into three categories: storage system, I/0 
system, and other. Certain codes have been included in the individual 
subroutine description if they have a special meaning in the context of that 
subroutine. The reader should not assume that the code(s) given in a particular 
subroutine description are the only ones that can be returned. 


Treatment of Links 


Generally, whenever the programmer references a link, the subroutine 
action is performed on the entry pointed to by the link. If this is the case, 
the only way the programmer can have the action performed on the link itself is 
if the subroutine has a chase switch and he sets the chase switch to 0. 
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active fne_err active fne_err_ 


Name: active fne_err_ 


The active fne_err_ Subroutine is called by active functions when they 
detect unusual status conditions. This subroutine formats an error message and 
then signals the condition active function_error. The default handler for this 
condition prints the error message and then returns the user to command level. 
(See "List of System Conditions and Default Handlers" in Section 6 of the MPM 
Reference Guide for further information.) 


Since this subroutine can be called with a varying number of arguments, it 
is not permissible to include a parameter attribute list in its declaration. 


Usage 


declare active fne_err_ entry options (variable); 


call active fne_err_ (code, caller, control string, argi, ..., argn); 


where: 

ie code (Input) 
is a standard status code (fixed bin(35)). 

2. caller (Input) 
is the name (char(*)) of the calling procedure. It can be either 
varying or nonvarying. 

3. control string (Input) 
Is an ioa subroutine control string (char(*)). (The ioa_ 
subroutine is described in the MPM Subroutines.) This argument is 
optional. See "Note" below. 

4, argi (Input) 
are ioa_ subroutine arguments to be substituted into control string. 
These arguments are optional. (However, they can only be used if 
the control string argument is given first.) See "Note" below. 

Note 


The error message prepared by the active fne_err_ subroutine has the 
t: 


caller: system_message user_message 
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active fne_err active fne err 


where: 


Ta caller 
is the caller argument described above and should be the name of the 
procedure detecting the error. 


2. system message 
~ is a standard message from a standard status table corresponding to 
the value of code. If code is equal to 0, no system message is 
returned. = 
3. user message 
~ is constructed by the ioa subroutine from the control string and 


argi arguments described “above. If the control string and argi 
arguments are not given, user message is omitted. = = 


Entry: active fne_err_$suppress name 


This entry point is functionally the same as active fne_ err_, but it suppresses 
the caller name and the colon at the beginning of the error message. The caller 
name is nevertheless passed to the active function error handler. 


Usage 


declare active fne_ err $suppress name entry options (variable); 


call active fne err $suppress name (code, caller, control string, 
argi,...argN); 


where all arguments are the same as above. 
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Name: add epilogue _handler_ 


The add epilogue handler _ subroutine is used to add an entry to the list of 
those handlers called when a process or run unit is terminated. A program 
established as an epilogue handler during a run unit is called when the run unit . 
is terminated. If the process continues after the run unit is terminated, the 
handler is discarded from the list of those called when the process is 
terminated. Hence, epilogue handlers established during a run unit are not 
retained beyond the life of the run unit. 


Usage 


declare add epilogue _handler_ entry (entry, fixed bin (35)); 
call add_epilogue_handler_ (ev, code); 
where: 


Acs ev 
is an entry value to be placed on the list of such values to be 
called when the run unit or process is cleaned up. 


Oe code 
is a standard status code. 


Note 


The add epilogue handler Subroutine effectively manages two lists of 
epilogue handlers: those for the run unit, if a run unit is active, and those 
for the process. While a run unit is active, it is not possible to add entries 
to the list for the process. There is no way to establish a process epilogue 
handler while a run unit is active. The caller of execute epilogue (logout, 
new proc, etc.) muSt indicate whether all or just the run unit handlers are to 
be invoked. 
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aim check aim check 


Name: aim check 


The aim check subroutine provides a number of entry points for determining 
the relationship between two access attributes. An access) attribute can be 
either an authorization or an access class. See also the read allowed , 
read write allowed_, and write allowed _ subroutines in this document. 4 7 


Entry: aim_check_ $equal 


This entry point compares two access attributes to determine whether they 
satisfy the equal relationship of the access isolation mechanism (AIM). 


Usage 


declare aim_check $equal entry (bit(72) aligned, bit(72) aligned) returns 
(bit(1) aligned); 


returned bit = aim_check $equal (acc_atti, acc_atte2); 


where: 

1. ace atti (Input) 
are access attributes. 

2. returned bit (Out put) 


is the result of the comparison. 
sl Bl ©) ace_atti equals acc att2 
mOMD ace_atti1 does not equal acc_att2 


Entry: aim check $greater 


This entry point compares two access attributes to determine whether they 
satisfy the greater-than relationship of the AIM. 


Usage 
declare aim_check $greater entry (bit(72) aligned, bit(72) aligned) returns 
(bit(1) aligned); 


returned bit = aim check $greater (ace_atti, acc _att2); 
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where: 

TM ace atti (Input) 
are access attributes. 

ea returned bit (Output) 


is the result of the comparison. 
ie ae: acc_att1 is greater than ace_atte 
"O"b ace_att1 is not greater than acc att2 


Entry: aim_check $greater_or_equal 


This entry point compares two access attributes to determine whether they 
satisfy either the greater-than or the equal relationships of the AIM. 


Usage 


declare aim check $greater_or_equal entry (bit(72) aligned, bit(72) 
aligned) returns (bit(1) aligned); 


returned bit = aim_check $greater_or_equal (ace att1, acc _att2); 


where: 

te ace atti (Input) 
are access attributes. 

2. returned bit (Output) 


is the result of the comparison. 
ba Wied acc_attl is greater than or equal to acc att2 
"OO" D acc_attl is not greater than or equal to ace atte 
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area_info_ area info 


Name: area info 


The area_info_ Subroutine returns information about an area. 


Usage 


declare area_info_ entry (ptr, fixed bin (35)); 


call area_info_ (info_ptr, code); 


where: 
Ts info_ptr (Input) 
points to the structure described in "Notes" below. 
ey code (Output) 
is a system status code. 
Notes 


The structure pointed to by info_ptr is described by the following PL/I 
declaration (defined by the system include file, area_info.incl.pl1: 


del 1 area _info aligned based, 

2 version fixed bin, 

2 control, 
3 extend bit(1) unaligned, 
3 zero_on_alloc bit(1) unaligned, 
3 zero on free  bit(1) unaligned, 
3 dont free bit(1) unaligned, 
3 no_freeing bit(1) unaligned, 
3 system bit(1) unaligned, 
3 mbz bit(30) unaligned, 

2 owner ehar(32) unaligned, 

2 n components fixed bin, 

2 size fixed bin(30), 

2 version of area fixed bin, 

2areap  ~ ptr, 

2 allocated blocks fixed bin, 

2 free blocks fixed bin, 

2 allocated words fixed bin(30), 

2 free_words fixed bin(30); 


1. version 
is set by the caller and should be 1. 


2. control 
are control bits describing the format and type of the area. 
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11. 


Ts 


13. 


15. 


16. 


extend 
indicates whether the area is extensible. 
m1"b yes 
"O"b no 


zero_on_ alloc 
indicates whether blocks are cleared (set to all zeros) at 
allocation time. 
eT yes 
"O™D: .d6 


zero. ion free 
indicates whether blocks are cleared (set to all zeros) at free 


time. 
"qth yes 
"OND no 


dont_free 
indicates whether free requests are disabled (for debugging). 
Wath yes 
NOND no 


no_ freeing 
indicates whether the allocation method assumes no freeing will be 


done. 
"qth yes 
"oth no 
system 
indicates whether the area is managed by the system. 
4th yes 
NONb no 
mbz 


is not used and must be zeros. 


owner 
is the name of the program that created the area if the area is 
extensible. 


n_components 
is the number of components in the area. 


size 
is the total number of words in the area. 


version of area 
is 0 for (old) buddy system areas and 1 for standard areas. 


areap 
is filled in by the caller and can point to any component of the 
area. 


allocated blocks 
is the number of allocated blocks in the area. 


free blocks 
is the number of free blocks in the area (not including virgin 
storage within components, i.e., storage after the last allocated 
block). 
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area _info_ area info 


17. allocated words 
is the number of allocated words in the area. 


18. free words 
is the number of free words in the area not counting virgin storage. 


No information is returned about version 0 areas except the version number. 


If the no_freeing bit is on ("1"b), the counts of free and allocated blocks 
are returned as 0. 
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ascii to ebcdic ascii to ebcdic 


Name: ascii to ebcdic_ 


The ascii to ebedic Subroutine performs isomorphic (one-to-one reversible) 
conversion from ASCII to EBCDIC. The input data is a string of valid ASCII 
characters. ~A valid ASCII character is defined as a 9-bit byte with an octal 
value in the range 0 < octal_value < 177. 


Entry: aseii_to_ebedic_ 


This entry point accepts an ASCII character string and generates an EBCDIC 
character string of equal length. 


Usage 


declare ascii_to_ebcdic_ entry (char(*), char(*)); 


call ascii_to_ebedic (ascii_in, ebedic out); 


where: 
‘Tes ascii_in (Input) 

is a string of ASCII characters to be converted. 
Bs ebedic out (Out put ) 


“is the EBCDIC equivalent of the input string. 


Entry: ascii_to_ebcdic $ae_ table 


This entry point defines the i28-character translation table used to 
perform conversion from ASCII to EBCDIC. The mappings implemented by the 
ascii_to_ebcdic and ebcdic to _ascii_ subroutines are isomorphic; i.e., every 
valid character has a unique mapping, and mappings are reversible. (See the 
ebedic_to_ascii_ subroutine.) The result of an attempt to convert a character 
that is not in the ASCII character set is undefined. 


Usage 


declare ascii_to_ebedic $ae_table char(128) external static; 
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ascii to ebcdic ascii to ebcedic_ 


ISOMORPHIC ASCII/EBCDIC CONVERSION TABLE 


ASCII EBCDIC 
GRAPHIC OCTAL HEXADECIMAL GRAPHIC 
NUL 000 00 NUL 
SOH 001 01 SOH 
STX 002 02 STX 
ETX 003 03 ETX 
EOF 004 37 EOT 
ENQ 005 2D ENQ 
ACK 006 2E ACK 
BEL 007 oF BEL 
BS 010 16 BS 
HT 011 05 HT 
LE 012 25 NL 
VT 013 OB VT 
FF 014 oc NP 
CR 015 OD CR 
SO 016 OE SO 
SI 017 OF SI 
DLE 020 10 DLE 
DC 1 021 11 DC 1 
DE2 022 12 DC2 
DC 3 023 13 ™ 
DC 4 024 3C DC 4 
NAK 025 3D NAK 
SYN 026 32 SYN 
ETB 027 26 ETB 
CAN 030 18 CAN 
EM 031 19 EM 
SUB 032 SF SUB 
ESC 033 27 ESC 
FS 034 1c IFS 
GS 035 1D IGS 
RS 036 TE IRS 
US 037 1F IuUs 

space O40 40 Space 
! 041 5A ! 
t o4e2 7F id 
# 043 7B # 
$ O44 5B $ 
% O45 6C 3 
& 046 50 & 
' O47 7D , 
( 050 4D ( 
) 051 5D ) 
# 052 5C * 
+ 053 HE + 
; 054 6B , 
- 055 60 - 
056 4B 
/ 057 61 / 
0 060 FO 0 
1 061 Fi 1 
2 062 E2 2 
3 063 F3 3 
4 064 FY 4 
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GRAPHIC OCTAL HEXADECIMAL GRAPHIC 


5 065 F5 5 
6 066 F6 6 
7 067 Py 7 
8 070 F8 8 
9 071 FQ 9 
072 7A 
; 073 5E ; 
< O74 4C < 
= 075 TE = 
> 076 6E > 
? O77 6F ? 
@ 100 TC @ 
A 101 C1 A 
B 102 C2 B 
C 103 C3 C 
D 104 C4 D 
E 105 C5 E 
F 106 C6 F 
G 107 C7 G 
H 110 C8 H 
I 111 C9 I 
J 112 D1 J 
K 113 De K 
L 174 D3 L 
M 115 D4 M 
N 116 D5 N 
@) 117 D6 0 
P 120 D7 P 
Q 121 D8 Q 
R 122 DY R 
S 123 E2 S 
T 124 E3 T 
U 125 E4 U 
V 126 E5 V 
W 127 E6 W 
X 130 ET xX 
Y 131 E8 b 4 
Z 132 EQ Z 
[ 133 AD { (see "Notes") 
\ 134 EO \ 
J 135 BD ] (see "Notes") 
* 136 SF logical NOT 
137 6D 

= 140 79 = 
a 141 81 a 
b 142 82 b 
c 143 83 e 
d 144 84 d 
e 145 85 e 
f 146 86 f 
g 147 87 g 
h 150 88 n 
i 151 89 i 
j 152 91 5 
k 153 92 k 
1 154 93 1 
m 155 94 m 
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GRAPHIC OCTAL HEXADECIMAL GRAPHIC 

n 156 95 n 

re) 157 96 re) 

p 160 Dit p 

q 161 98 q 

r 162 99 r 

s 163 A2 Ss 

t 164 A3 t 

u 165 AY u 

Vv 166 A5 V 

W 167 A6 W 

X 170 AT X 

y 171 A8 y 

Z Tt2 AQ Z 

{ Te3 CO { 

174 UF solid bar 
} 175 DO } 

x 176 Al . 

DEL a a 07 DEL 


Notes 


The graphics ("([" and "]") do not appear in (or map into any graphics that 
appear in) the standard EBCDIC character set. They have been assigned to 
otherwise "illegal" EBCDIC code values in conformance with the bit patterns used 
by the TN text printing train. 


Calling the ascii_to_ebcdic_ subroutine is as efficient as using the PL/I 
translate builtin, since conversion is performed by a single MVT instruction and 
the procedure runs in the stack frame of its caller. 


This mapping differs from the ASCII to EBCDIC mapping discussed in "Punched 
Card Codes" in Section 5 of the MPM Reference Guide. The characters that differ 
when mapped are: [ ] \ and NL (newline). 
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Name: assign _ 


The assign subroutine assigns a specified source value to a specified 
target. This subroutine handles the following data types: 1-12, 19-22, 33, 34,. 
41-46. Any other type will produce an error. This subroutine uses rounding in 
the conversion when the target is floating point or when the source is floating 
and the target is character, and uses truncation in all other cases. 


Usage 
declare assign entry (ptr, fixed bin, fixed bin(35), ptr, fixed bin, 
fixed bin(35)); 


call assign (target ptr, target _ type, target _length, source ptr, 
source type, source length); 


where: 
Ls target ptr (Input) 
points to the target of the assignment; it can contain a bit offset. 
ois target type (Input) 
specifies the type of the target; its value is 2*M+P where M is the 
Multics standard data type code (see the MPM Reference Guide) and P 
is 0 if the target is unpacked and 1 if the target is packed. 
3. target length (Input) 
is the string length or arithmetic scale and precision of the 
target. If the target is arithmetic, the target length word 
consists of two adjacent unaligned halfwords. The left halfword is 
a fixed bin(17) representing the signed scale and the right halfword 
is a fixed bin(18) unsigned integer representing the precision. The 
include file encoded precision.incl.pl1 declares this as: 
del 1 encoded precision based aligned, 
2 scale fixed bin(17) unaligned, 
prec fixed bin(18) unsigned unaligned; 
4, source ptr (Input) 
points at the source of the assignment; it can contain a bit offset. 
ae source type (Input) 
specifies the source type using the same format as target type. 
6. source length (Input) 


is the string length or arithmetic scale and precision of the source 
using the same format as target_length. 
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Entry: assign $computational _ 


The assign $computational entry assigns a specified source value to a 
specified target. It can handle any computational Multics data type. This 
includes all PL/I computational data and all COBOL and FORTRAN data types. This 
entry uses the same rules for rounding and truncation as assign . 


Usage 


declare assign $computational entry (ptr, ptr, fixed bin(35)); 


call assign $computational (tar_str_ptr, sre _str_ptr, code); 


where: 

i tar_str_ ptr (Input) 
is a pointer to a structure which defines the address and attributes 
of the target. The format of this structure is defined below. 

cap sre _str_ptr (Input) 
is a pointer to a structure giving the attributes of the source. 
This structure has the same format as the one used for the target. 

3. code (Output) 
is a standard system code. It will be zero if the conversion was 
sucessful, or error table $bad conversion if either data type was 
not computational. Ee, 15 also possible that the conversion 
condition will be signalled, if the source data can not be converted 
to the requested target type. 

Notes 


The format of the structures used to describe the source and target data is 


given by computational data.incl.pl1l. It is: 
dcl 1 computational data aligned based, 
2 address ptr aligned, 
2 data type fixed bin(17), 
2 flags aligned, 
3 packed bit(1) unal, 
3 pad bit(35) unal, 
2 prec or length fixed bin(24), 
2 scale fixed bin(35), 
2 picture image ptr ptr aligned; 


12/79 7-16 AK92A 


assign | assign _ 


where: 


Tex address 
is a pointer to the data where the data is (source) or where it 
is to go (target). It is the responsibility of the caller to 
ensure that there is sufficient room for the target. 


2s data type 
is a standard Multics data type. A list of all Multics data 


types appears in the MPM Reference Guide. The include file 
std descriptor types.incl.pl1 defines symbolic names for these 
types. 

36 packed 
is "1"b if the data is packed. 

a pad 
is reserved for expansion and must be all "O"b. 

Ds prec _or length 
is the arithmetic precision or string length of the data, as 
appropriate. 

O% scale 


is the arithmetic scale factor of the data, or zero if the data 
is not arithmetic. 


—~ 


picture image ptr 
for picture data, is a pointer to the picture image block for 
the picture, otherwise it is ignored. A picture image block is 
a structure in the runtime symbol table. Only PL/I and the 
Multics debuggers know how to access it, so user programs 
should not try to convert to or from pictures using this entry. 


miiMVUR LS ae avvutr OO Awake Vita 


Entry: assign round _ 


This entry assigns a source value to a target value, but always rounds. 
Otherwise it is identical to assign . 


Entry: assign truncate _ 


This entry is identical to assign except that it always truncates. 
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Name: change default wdir_ 


The change default wdir subroutine changes the user's current default 
working directory to the directory specified. See the description of the 
change wdir and change default wdir commands in the MPM Commands for a 


discussion of the default working directory. 


Usage 


declare change default wdir_ entry (char(168), fixed bin(35)); 


call change default wdir_ (path, code); 


where: 

Ts path (Input) 
is the pathname of the directory that is to become the default 
working directory. 

eo. code (Output) 


is a storage system status code. 
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Name: char_to_numeric_ 


The char _to_numeric subroutine converts a user-supplied string toa 
numeric type, or signals the conversion condition if it cannot be converted. 
The attributes of the numeric data created are returned. 


Usage 


declare char _to numeric_ entry (ptr, fixed bin(35), fixed bin(35), ptr, 
fixed bin(21)); 


call char_to_numeric_ (target ptr, ene type, ene prec, source ptr, 
source len); 


where: 

deg target ptr (Input) 
points to a buffer where the numeric data may be written. No check 
is made that the buffer is large enough to hold the data. 

2% enc type (Output) 
is the encoded type of the data created. Its value is 2*M+P, where 
M iS a Standard Multics type code, and P is 1 if the data is packed, 
or 0°. =f 16 25 a10t, (P should always be 0.) The value of Multics 
type codes are defined in the MPM Reference Guide. 

s enc prec © (Output) 
is the encoded precision of the data created. The format of an 
encoded precision is given by encoded precision.incl.pl1. See the 
description of the assign subroutine. 

4, source ptr (Input) 
points to the character string to convert to numeric. 

5. source len (Input) 


is the number of characters in the input string. 
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Name: check star_name_ 


The check star name subroutine validates an entryname to ensure that it 
has been formed according to the rules for constructing star names. For more 
information on star names, see the MPM Reference Guide. It also returns a 
nonstandard status code that indicates whether the entryname is a star name and 
whether it is a star name that matches every entryname. 


Entry: check star_name $path 


This entry point accepts a pathname as its input and validates the final 
entryname in that pathname. 


Usage 


declare check star_name $path entry (char(*), fixed bin(35)); 


call check star _ name $path (path, code); 


where: 
1. path (Input) 
is the pathname whose final entryname is to be validated. Trailing 
spaces in the pathname character string are ignored. 
2 code (Output) 
is a standard status code. It may have the following values: 
0 the entryname is valid and is not a star name (does not contain 
asterisks or question marks). 
1 the entryname is valid andis a star name (does contain 
asterisks or question marks). 
2 the entryname is valid and is a star name that matches every 


entryname (either **, or *.**, or *®*,%), 

error table $badstar 
the entryname is invalid. It violates one or more of the rules 
for constructing star names. 
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Entry: check star_name_$entry ~ 


This entry point accepts the entryname to be validated as input. 


Usage 


declare check star_name_$entry entry (char(*), fixed bin(35)); 


call check star_name_$entry Centryname, code); 


where: 

Ts entryname 
is the entryname to be validated. Trailing spaces in the entryname 
character string are ignored. 


Oe code 
is as described above. 


Notes 


The procedure for obtaining a list of directory entries that match a given 
Star name is explained in the description of the hes $star_ subroutine in this 
document. 


The procedure comparing an entryname with a given star name is explained in 
the description of the match_star_name_ subroutine in this document. 
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Name: component_info_ 


This subroutine returns information about a component of a2 bound segment 
similar to that returned by object_info_. The component may be specified either 
by name or by offset. 


Entry: component_info_ $name 


This entry point specifies the component by name. 


Usage 


declare component info $name entry (ptr, char(32) aligned, ptr, 
fixed bin(35)); 


call component _info_$name (seg_ptr, comp name, arg ptr, code); 


where: 
1 seg ptr (Input) 
is a pointer to the bound segment. 
2s comp name (Input) 
is the name of the component. 
3 arg ptr (Input) 
is a pointer to a structure to be filled in (see "Notes" below). 
4, code (Output) 


is a standard status code. 


Entry: component_info_$offset 


This entry point specifies the component by its offset. 


Usage 
declare component info $offset entry (ptr, fixed bin(18), ptr, 
fixed bin(35)); 


call component info $offset (seg ptr, offset, arg ptr, code); 


7-18 AK92 


component info _ 


component _info_ 


where: 
1. seg ptr (Input) 
is a pointer to the bound segment. 
ee, offset (Input) 
is an offset into the bound segment corresponding to the text, 
internal static or symbol section of some component. 
ooo. 
are as above. 
Notes 
The structure’ to be filled in (a declaration of which is found in 
component info.inecl.pl1) is declared as follows: 
Ged” ACR aligned, 
2 del version fixed bin, 
2 name char(32) aligned, 
2 text start pur, 
2 stat start per; 
2 symb start per, 
2 defblock ptr ptr, 
2 text Ing fixed bin, 
2 stat lng fixed bin, 
2 symb lng fixed bin, 
2 n- blocks fixed bin, 
2 standard bit(1) aligned, 
2 compiler char(8) aligned, 
2 compile time fixed bins 1). 
2 user _id ehar(32) aligned, 
2 evers aligned, 
3 offset bit(18) unaligned, 
3 length bit(18) unaligned, 
2 comment aligned, 
3 offset bit(18) unaligned, 
3 length bit(18) unaligned, 
2 source map fixed bin; 
where: 
1. del version 
is the version number of this structure. It is set by the caller 
and must be 1. 
2. name 
is the name of the component, i.e., the name specified in a bindfile 


objectname statement; 


3. text_start 


is a pointer to the base of the 


4, stat start 


is a pointer to the base of the 
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also, the name of the component as archived. 
component's text section. 


component's internal static. 
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component _info_ 


— 


10. 


11. 


le. 


13. 


14. 


15. 


16. 


17. 


183 


19. 


symb_ start 
is a pointer to the base of the 


defblock ptr 
is a pointer to the componentis 


text Ing 

is the length, in words, of the 
stat_ling 

is the length, in words, of the 
symb_lng 


is the length, in words, of the 


n_blocks 


component info 


component's symbol section. 


definition block. 


component's text section. 


component's internal static. 


component's symbol section. 


is the number of blocks in the component's symbol section. 


Standard 


is on if the component is in standard object format. 


compiler 


is the name of the component's compiler. 


compile time 


1s a clock reading of the date/time the component was compiled. 


user_id 
is the standard Multics User_id 


evers.offset 


of the component's creator. 


is the offset of the printable version description of the 
component's compiler, in words, relative to symb_ start. 
evers.length 
is the length, in characters, of the component's compiler version. 
comment.offset 
is the offset of the component's compiler comment, in words, 
relative to symb_ start. 
comment.length 
is the length, in characters, of the component's comment. 
source map 
is the offset of the component's source map structure, in words, 


relative to symb start. 
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Name: condition interpreter _ 


The condition interpreter subroutine can be used by subsystem condition 
handlers to obtain a formatted error message for all conditions except quit, 
alrm, and cput. Some conditions do not have messages and others cause special 
actions to be taken. These are described in "Notes" below. (For more 
information on conditions, see the MPM Reference Guide.) 


Usage 
declare condition interpreter _ entry (ptr, ptr, fixed bin, fixed bin, ptr, 
char (*),. ptr; pir): 


call condition interpreter _ (area_ptr, m_ptr, mlng, mode, mc_ptr, 
cond name, we ptr, info ptr); 


where: 

Le area ptr (Input) 
is a pointer to the area in which the message is to be allocated, if 
the message is to be returned. The area size should be at least 300 
words. If null, the message is printed on the error output I/0 
Switch. 

is m ptr (Output) 
points to the allocated message if area ptr is not null; otherwise 
it is not set. 

3. ming (Output) . 
is the length (in characters) of the allocated message if area ptr 
is not null. If area _ ptr is null, the length is not set. Certain 
conditions (see "Notes" below) have no messages; in these cases, 
mlng is equal to 0. 

4, mode (Input) 
is the desired mode of the message to be printed or returned. It 
can have the following values: 
1 normal mode 
2 brief mode 
3 long mode 

5. me ptr (Input) 
if not null, points to machine conditions describing the state of 
the processor at the time the condition was raised. 

6. cond name (Input) 
is the name of the condition being raised. 

rae we ptr (Input) 
is usually null; but when me_ ptr points to machine conditions from 
ring 0, we_ptr points to alternate machine conditions. 

8. into ptr (Input) 


if not null, points to the information structure described under 
"List of System Conditions and Default Handlers" in the MPM 
Reference Guide. 
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Notes 


The following conditions cause a return with no message 
command error 

command question 

finish 

stringsize 
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Name: continue _to_ signal | 


The continue to_ signal | Subroutine enables an on unit that cannot 
completely handle a condition to tell the signalling program, upon its return, 
to search the stack for other on units for the condition. The search continues 
with the stack frame immediately preceding the frame for the block containing 
the on unit. However, if a separate on unit for the any other condition is 
established in the same block activation as the caller of the 
continue to signal subroutine, that on unit is invoked before the stack is 
searched further. 


Usage 


declare continue to signal entry (fixed bin(35)); 


call continue _to signal (code); 


where code (Output) is a standard status code and is nonzero if 
continue to signal was called when no condition was signalled. I 
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Name: convert aim attributes 


The convert _aim_attributes__ subroutine converts a bit(72) aligned 
representation of an access authorization or access class into a character 
string of the form: 


where LL...L is an octal sensitivity level number, and CC...C is an octal string 
representing the access category set. : 


Usage 


declare convert_aim_attributes_ entry (bit(72) aligned, char(32) aligned); 


call convert_aim_attributes_ (aim_bits, aim_chars); 


where: 


1. aim_bits (Input) 
is the binary representation to be converted. 


ee aim_chars (Output) 
is the character string representation. 


Notes 


Only significant digits of the level number (usually a single digit from 0 
to 7) are printed. 


Currently, only 18 access category bits are used, so that only six octal 
digits are required to represent access categories. Therefore, aim chars is 
padded on the right with blanks, which may be used at a later time for 
additional access information. Trailing zeros are not stripped. 


If either the level or category field of aim_bits is invalid, the erroneous 
field is returned as full octal (6 digits for level, 12 digits for category), 
followed by the string "(undefined)". 
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Name: convert_dial_ message _ 


The convert dial message subroutine is used in conjunction with the 
dial _manager_ subroutine to control dialed terminals. It converts an event 
message received from the answering service over a dial control event channel 
into status information more easily used by the user. 


Entry: convert dial message $return_io module 


This entry point is used to process event messages from the answering 
service regarding the status of a dialed terminal or an auto call line. In 
addition to returning line status, this entry point also returns the device name 
and I/O module name for use in attaching the line through the iox_ subroutine. 
See the MPM Subroutines for further description of the iox_ subroutine. 


Usage 


declare convert_dial_ message $return_io_module entry (fixed bin(71), 
char(*), char(*), fixed bin, 1 aligned, 2 bit(1) unmal, 2 bit(1) unal, 
2 bit(i) unal, 2 bit(33) unal, fixed bin(35)); 


call convert_dial_message $return_io_module (message, channel name, 
io module, n_ dialed, flags, code); . 


where: 
dss message (Input) 
is the event message to be decoded. 
2. channel_name (Output) 
is the name of the channel that has dialed up or hung up. 
3. io module (Output) 
is the name of the iox  I/0 module to be used with the assigned 
device. 
4, n_dialed (Output) 
is the number of terminals currently dialed to the process or -1. 
5. flags (Output) 
is a bit string of the following structure: 
del 1 flags aligned, 
2 dialed_up bit(1) unal, 
2 hung_up bit(1) unal, 
2 control bit(1) unal, 
2 pad bit(33) unal; 
Only the first three bits have meaning, and only one can be on at a 
time. See "Notes" below for complete details. 
6. code (Output) 


is a standard status code. 
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Notes 


The message may be either a control message or an informative message. 
Informative messages have flags.control off ("0"b), n_dialed is set to -1, 
channel is set to the name of the channel involved, io module is set to the name 
of an I/O module, and either flags.dialed_up or flags.hung_up is on, indicating 
that the named channel has either just dialed up or just hung up. The io module 
name is provided as a convenience; the caller is not required to use the name 
returned by this subroutine. 


Control messages have flags.control on ("1"b), and n_dialed is set to the 
number of dialed terminals or -1. The code is either O (request accepted) or 
one of the following values: 


error table $action _not_performed 
the requested action was not performed; typically, this indicates an 
attempt to manipulate a channel that the requesting process can not 
control. 


error table $ai_out_range 
access to the requested channel is prohibited by AIM. 


error_table $bad_ name 
the channel _ name does not conform to required syntax. 


error table $badcall 
the dial message was -1. The dial _mManager_ subroutine will set 
dial_manager_arg.dial message to -1 when an error occurs and there is 
no anSwering service dial_message to return. 


error_table $bigarg 
the dial _out_distination is too long. 


error table $dial_ active 
the process is already serving a dial qualifier. 


error _table $dial_id_ busy 
the dial _qualifier is already being used by another process. 


error _table $insufficient_access 
the running process does not have the access permission required to 
perform the requested operation. 


error table $invalid resource state 
the channel is not configured to allow the requested operation. 


error_table $name_not_ found 
the dial _qualifier is not registered. 


error_table $no_ connection 
it was not possible to complete the connection, e.g., dial-out 
failure. 


error table $no_dialok 
the requesting process does not have the dialok attribute. 


error _table $order_error 
an error occurred while processing an order on this channel. 
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error _table $request_not_ recognized 
indicates a software error. 


error table $resource not free 
the requested channel is already in use. 


error _table $resource unavailable 
no channel could be found that satisfied required characteristics. 


the channel specified does not exist. 


error table $unable to_check access 
typically indicates that the process does not have required access, 
but may indicate an administrative error. 


error table $unimplemented_version 
the version of the dial_manager_arg structure supplied is not 


Supported by dial_manager_. This error code may also indicate an 


error table $resource unknown | 
internal software error. | 
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The convert ipe code _ subroutine is obsolete and has been deleted. 
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Name: convert status _ code_ 


The convert status_code subroutine returns the short and long” status 
messages from the standard status table containing the given status code. See 
"Status Codes" in Section 7 of the MPM Reference Guide. 


Usage 


declare convert_status_ code entry (fixed bin(35), char(8) aligned, 
char(100) aligned); 


call convert_status_code_ (code, shortinfo, longinfo); 


where: 
1. code (Input) 
is a standard status code. 
ei shortinfo (Out put ) 
is a short status message corresponding to code. 
3. longinfo (Output) 
is a long status message corresponding to code; the message is 
padded on the right with blanks. 
Note 


If code does not correspond to a valid status code, shortinfo is 
"XXXXXXXX", and longinfo is "Code ddd", where ddd is the decimal representation 
of code. 
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Name: copy _acl_ 


The copy_acl_ subroutine copies the access control list (ACL) from one 


file, segment, multisegment file, or directory to another, replacing the current 
ACL if necessary. 


Usage 
declare copy acl_ entry(char(*), char(*), char(*), char(*), bit(1) aligned, 
fixed bin(35)); 


call copy _acl_ (source dir, source ent, target dir, target_ent, 
target_error_sw, code); 


where: 

1. source dir (Input) 
is the pathname of the directory containing the source file or 
source directory whose ACL is to be copied. 

2. source ent (Input) 
is the entryname of the source file or source directory. 

3. target _dir (Input) 
is the pathname of the directory containing the target file or 
target directory whose ACL is replaced. 

4. target_ent (Input) 
is the entryname of the target file or target directory. 

5. target _error_sw (Output) 
is "O"b if the status code reflects an error in listing the ACL of 
the source file or directory, and is "1"b if the code reflects an 
error in replacing the ACL of the target file or directory. 

6. code (Output) 
is a standard status code. 

Notes 


An attempt to copy the ACL from a source file to a target directory, or 
from a source directory to a target file causes an error. Source and target 
must both be a file, or both a directory. 


Links are chased in the processing of the source and target pathnames. 
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Name: create_ips mask 


The create ips mask _ subroutine returns a bit string that can be used to 
disable specified ips interrupts (also known as ips signals). 


Usage 


declare create ips mask_ entry (ptr, fixed bin, bit(36) aligned); 


call create ips mask _ (array_ptr, lng, mask); 


where: 

1. array ptr (Input) 
is a pointer to an array of ips (interprocess signal) names that are 
echar(32) aligned. 

2. lng (Input) 
is the number of elements in the above array. 

as mask (Output) 
is a mask that disables all of the ips signals named in the array 
pointed to by array_ptr. (See "Notes" below.) 

Notes 


If any of the names are not valid ips signal names, the condition 
create ips_mask_ err is signalled. 


If the first name in the array is -all, then a mask is returned that masks 
all interrupts. 


Currently the allowed ips names are: 


quit 
eput 
alrm 
neti 
sus 

trm_ 
wkp_ 


The returned mask contains a "0"b in the bit position corresponding to each ips 
name in the array, and a "1"b in all other bit positions. The bit positions are 
ordered as in the above list. It should be noted that it is necessary to 
complement this mask (using a statement of the form "mask = “mask") in cases 
where the requirement is for amask with "1" bits corresponding to specified 
interrupts. An ips mask is used as an argument to the following entry points: 
hes $reset_ips mask, hes $set_automatic ips mask, and hes $set_ips mask. 
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Name: cross ring 


The cross ring I/0 module allows an outer ring to attach a switch to a 
preexisting switch in an inner ring, and to perform I/O operations by forwarding 
I/O from the attachment in the outer ring through a gate to an inner ring. The 
cross ring I/O module is not called directly by users; rather the module is 
accessed through the I/O system. 


Attach Descriptions 
cross ring Switch name N 
where: 


Ane Switch name 
is a previously registered switch name in ring N. 


ae N 
is a ring number from 0 to 7. 


Opening 


The inner ring switch may be open or not. If not open, it will be opened 
on an open call. All modes are supported. 


Close Operation 


The inner switch is closed only if it was opened by cross ring . 


Other Operations 


All operations are passed on to the inner ring I/O switch. 


Notes 


This I/O module allows a program in an outer ring, if permitted by the 
inner ring, to use I/O services that are available only from an inner ring via 
cross ring io $allow cross. By the use of the cross ring io $allow cross 
subroutine a subsystem writer is able to introduce into an outer ring 
environment many features from an inner ring, thereby tailoring it to fit the 
user's specific needs. 


The switch in the inner ring must be attached by the inner ring before 
cross ring can be attached in the outer ring. 
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Name: cross ring io $allow_cross 


The cross ring io $allow_cross entry point must be called to allow use of 
an I/O switch via cross-ring attachments from an outer ring. The call must be 
made in the inner ring before the outer ring attempts to attach. 


Usage 


declare cross ring io $allow_cross entry (char(*), fixed bin, 
fixed bin(35)); 


call cross ring io $allow_cross (switch name, ring, code); 


where: 
1s switch_name (Input) 
is the inner ring switch name. 
2. ring (Input) 
is the highest validation level from which switch name may be used. 
Ss code (Output) 
is a standard status code. 
Notes 


This entry may be called more than once with the same switch name argument. 
Subsequent calls are ignored. 
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Name: ev bin 


The cv_bin_ subroutine converts the binary representation of an integer (of 
any base) to a 12-character ASCII string. 


Usage 


declare cv_bin_ entry (fixed bin, char(12) aligned, fixed bin); 


call cv_bin_ (n, string, base); 


where: 
is n (Input) 
is the binary integer to be converted. 
as string (Output) 
is the ASCII equivalent of n. 
oF base (Input) 


is the base to use in converting the binary integer (e.g., base is 
10 for decimal integers). 


Entry: cv_bin_$dec 


This entry point converts the binary representation of an integer of base 
10 to a 12-character ASCII string. 


Usage 


declare cv_bin $dec entry (fixed bin, char(12) aligned); 


call cv_bin_$dec (n, string); 


where: 
Tz n (Input) 

is the binary integer to be converted. 
ce string (Output) 


is the ASCII equivalent of n. 
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Entry: cv_bin_ $oct 


This entry point converts the binary representation of an octal integer to 
a 12-character ASCII string. 


Usage 


declare cv_bin_$oct entry (fixed bin, char(12) aligned); 


call cv_bin_$oct (n, string); 


where: 
WV n (Input) 
is the binary integer to be converted. 
2. string (Output) 
is the ASCII equivalent of n. 
Note 


If the character-string representation of the number exceeds 12 characters, 
then only the low-order 12 digits are returned. 
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Name: ev dec_ 


The cv_dec_ function accepts an ASCII representation of a decimal integer 
and returns the fixed binary(35) representation of that number. (See also 
ev_dec_ check .) 


Usage 


declare cv_dec_ entry (char(*)) returns (fixed bin(35)); 


a <= ev_dec_ (string); 


where: 
te string (Input) 

is the string to be converted. 
2. a (Output) 

is the result of the conversion. 
Note 


If string is not a proper character representation of a decimal number, a 
will contain the converted value of the string up to, but not including, the 
incorrect character within the string. 
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Name: ev_dec_check_ 


This function differs from cv_ dec fe) 


ly in that a code is’ returned 
indicating the possibility of a conversion error 


(See also cv. dec: +) 


n 
O° 


Usage 


declare cv_dec_check_ entry (char(*), fixed bin(35)) 
returns (fixed. bin(35)); 


a = cv_dec_ check (string, code); 


Ts string (Input) 
is the string to be converted. 


2. code (Output) 
is a code that equals 0 if no error has’ occurred; otherwise, it is 
the index of the character of the input string that terminated the 
conversion. See "Note" below. 


ce a (Output) 
is the result of the conversion. 


Note 


Code is not a standard status code and, therefore, cannot be passed to 
com_err_ and other subroutines that accept only standard status codes. 
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Name: cv_dir mode_ 


The cv_dir_mode_ subroutine converts a character string containing access 
modes for directories into a bit string used by the ACL entries. 


declare cv_dir_mode_ entry (char(*), bit(*), fixed bin(35)); 


call cv_dir_mode_ (char_modes, bit modes, code); 


where: 
ie char modes (Input) 
are the character string access modes. 
Zz bit modes (Output) 
are the bit string access modes. 
3 code (Output) 
is a standard status code. It may be: 
error table $bad acl mode 
if char_modes contains an invalid directory access mode 
character 
Notes 
If ‘char modes is “null” or "“n", bit modes is ‘set to “0O"Db. The mode 
characters in char_modes may occur in any order. Spaces are ignored. The 


following table indicates what bit in bit modes is turned on when the access 
mode character is found. 


Access Mode Bit in bit modes 
Ss 1 
m 2 
a 3 


12/79 1-34.17 AK92A 


This page intentionally left blank. 


AK92A 


ev_entry_ cv_entry 


Name: cv_entry_ 


The cv_entry function converts a virtual entry to an entry value. A 
virtual entry is a cnaracter-string representation of an entry value. The types 
of virtual entries accepted are described under "Virtual Entries" below. 


Usage 


declare cv_entry_ entry (char(*), ptr, fixed bin(35)) returns (entry); 


entry value = cv_entry (ventry, referencing ptr, code); 


where: 

1. ventry (Input) 
is the virtual entry to be converted. See "Virtual Entries" below 
for more information. 

2 referencing ptr (Input) 
is a pointer to a segment in the referencing directory. This 
directory is searched according to the referencing dir search rule 
to find the entry. A null pointer may be given if the 
referencing dir search rule is not to be used. 

3% code (Output) 
is a standard status code. 

4, entry value (Output) 


is the entry vaiue tnat resuits from the conversion. 


Virtual Entries 


The ev_entry function converts virtual entries that contain one or two 
components -=- a segment identifier and an optional offset into the segment. 
Altogether, eight forms are accepted. They are shown in the table below. 


In the table that follows, Wis an octal word offset from the beginning of 
the segment. It may have a value from 0 to 777777 inclusive. 
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Virtual 

Entry Interpretation 

path|W entry at octal word W of segment identified by absolute or 
relative pathname path. 

path} same as path{0. 

path;entry pt entry at word identified by entry point entry pt in segment 


identified by path. 


dir>entry$entry pt entry at word identified by entry point entry pt in segment 
identified by pathname dir>entry. 


<dir>entry$entry pt entry at word identified by entry point entry pt in segment 
identified by pathname <dirD>entry. 


<entry$entry pt entry at word identified by entry point entry pt in segment 
identified by pathname <entry. 


path same as pathi[entry path]. If path contains no ">" or "<" 
characters, it is interpreted as a ref_name. 


ref nameg$entry pt entry at word identified by entry point entry pt in segment 
found via search rules whose reference name is ref_name. 


ref name$Ww entry at octal word W of segment found via search rules 
whose reference name is ref_name. 


ref name$ same as ref name$0. 
ref name same as ref_nameg$ref_name. 
Notes 


Use of a pathname in a virtual entry causes the referenced segment to be 
initiated with a reference name equal to its final entryname. Name duplication 
errors occurring during the initiation are resolved by terminating the 
previously known name. 


The referencing ptr is used in a call to the hes $make_ entry entry point. 
Refer to the description of this entry point in the MPM Subroutines for more 
. information. 


The cv_entry_ function returns an entry value that may be used in a call to 
cu_$generate call. If an entry pointer is required, rather than an entry 
variable, make a call to cu_$decode_ entry value. (The cu_ subroutine is 
documented in the MPM Subroutines.) For pointers not used as entry pointers, 
use the cv_ptr_ function to convert a virtual pointer. 


A virtual entry not containing the "$" or "|" characters is interpreted as 
a pathname if it contains a ">" or "<" character, otherwise, it is a reference 
name, 
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Name: cv hex 


The cv hex function takes an ASCII representation of a hexadecimal integer 
and returns the fixed binary(35) representation of that number. The ASCII 
representation may contain either uppercase or lowercase characters. (See also 
ev_hex_check_.) 


Usage 


declare cv_hex_ entry (char(*)) returns (fixed bin(35)); 


a = cv_hex_ (string); 


Ais string (Input) 
is the string to be converted. It must be nonvarying. 


2s a (Out put) 
is the result of the conversion. 


yews AK92 


ev_hex_ check_ ev_hex_check_ 


Name: ev_hex_check_ 


This function differs from the cv hex function only in t 
returned indicating the possibility of a conversion error. (See also cv hex .) 


Usage 


declare cv_hex_check_ entry (char(*), fixed bin(35)), 
returns (fixed bin(35)); 


a = cv_hex_ check (string, code); 


where: 

1. string (Input) 
is the string to be converted. It must be nonvarying. 

Ons code (Out put) 
is a code that equals 0 if no error occurred; otherwise, it is the 
index of the character that terminated the conversion. See "Note" 
below. 

33 a (Output) 
is the result of the conversion. 

Note 


Code is not a standard status code and, therefore, cannot be passed to 
com_err_ and other subroutines that accept only standard status codes. 
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Name: cv_mode_ 


The cv_mode_ subroutine converts a character string containing access modes 
for segments into a bit string used by the ACL entries. 


Usage 


declare cv_mode_ entry(char(*), bit(*), fixed bin(35)); 


call cv_mode_ (char_modes, bit_modes, code); 


where: 
Ts char modes (Input) 

are the character string access modes. 
oe bit modes (Output) 

are the bit string access modes. 
3. code (Output) 

is a standard status code. It may be: 

error table $bad_ acl mode 

if char_mode contains an invalid segment access mode character 
Notes 
If char modes is "null" or "n", bit modes is set to "0O"b. The mode 

characters in char modes may occur in any order. Spaces are ignored. The 


following table indicates what bit in bit modes is turned on when the access 
mode character is found. 


Access Mode Bit in bit modes 
ig i 
e 2 
W 3 
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Name: ev oct 


The ecv_oct_ function takes an ASCII representation of an octal integer and 
returns the fixed binary(35) representation of that number. (See also 
ev_oct_check .) 


Usage 


declare cv_oct_ entry (char(*)) returns (fixed bin(35)); 


a = ev_oct_ (string); 
where: 
1 string (Input) 


is the string to be converted. 


2. a (Out put ) 
is the result of the conversion. 
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Name: ev_oct_check_ 


This function differs from the ev oct function only in that a code is 
returned indicating the possibility of a conversion error. (See also cv_oct_.) 


Usage 
declare cv_oct_check_ entry (char(*), fixed bin(35)) returns 
(fixed bin(35)); 


a = cv_oct_ check. (string, code); 


le string (Input) 
is the string to be converted. It must be nonvarying. 


2. code (Out put) 
is a code that equals O if no error’ occurred; otherwise it is the 
index of the character that terminated the conversion. See "Note" 
below. 


3. a (Output) 
is the result of the conversion. 


Note 


Code is not a standard status code and, therefore, cannot be passed to 
com_err_ and other subroutines that accept only standard status codes. 


7-40 AK92 


ev_ptr_ ev_ptr_ 


Name: cv_ptr_ 


The cv_ptr_ function converts a virtual pointer to a pointer value. A 
virtual pointer is a character-string representation of a pointer value. The 
types of virtual pointers accepted are described under "Virtual Pointers" below. 


Usage 


declare ov ptr_ entry (char(*), fixed bin(35)) returns (ptr); 


ptr_value = cv_ptr_ (vptr, code); 


where: 

Ts vptr (Input) 
is the virtual pointer to be converted. See "Virtual Pointers" 
below for more information. 

2. code (Out put ) 
is a standard status code. 

Se ptr_value (Output) 


is the pointer that results from the conversion. 


Entry: ev _ptr_$terminate 


This entry point is called to terminate the segment that has been initiated 
by a previous call to cv_ptr_. 


Usage 


a re es Poe cre ere eee : 
declare cv tr $terminate (ptr) 
’ 


call cv_ptr_$terminate (ptr_value); 


where ptr_value (Input) is the pointer returned by the previous call to cv_ptr_. 


Notes 


Pointers returned by the cv ptr function cannot be used as entry pointers. 
The cv ptr function constructs the returned pointer to a segment in a way that 
avoids copying of the segment's linkage and internal static data into the 
combined linkage area. The ev entry function is» used to convert virtual 
entries to an entry value. > 7 
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The segment pointed to 


reference name. 


this null reference name. 


Virtual Pointers 


The 
components 
Altogether, 


-- a 


In the table that follows, 


the segment. It 


cv_ptr_ function 
segment identifier 
fourteen forms are accepted. 


may have a value from 


bit offset within the word. 


Virtual 
Pointer 


pathiW(B) 


pathiW 
path} 
path 


pathjentry pt 


dir>entry$entry pt 


<dir>dentry$entry pt 


<entry$entry pt 


ref name$entry pt 


ref name$W(B) 


ref name$w 


ref name$ 


12/79 


converts virtual 


by the returned ptr value is 


pointers that 


and an optional offset 


Wiis 
0 to 7FTTTiT inclusive. -B 


contain one 
into the segment. 
They are shown in the table below. 


cv_ptr_ 


- initiated with a null 
The cv_ptr_ $terminate entry point should be called to terminate 


or two 


an octal word offset from the beginning of 
is a decimal 


It may have a value from 90 to 35 inclusive. 


Interpretation 


points to octal word W, decimal bit B of segment identified 
by absolute or relative pathname path. 


same as 
same as 
same as 


points 
segment 


points 
segment 


points 
segment 


points 
segment 


points 
segment 


points 


pathiW(0). 

path;0(0). 

path;0(0). 

to word identified by entry point 
identified by path. 

to word identified by entry point 
identified by pathname dirDentry. 

to word identified by entry point 


identified by pathname <dir>Dentry. 


to word identified by entry point 
identified by pathname <entry. 
to word identified by entry point 


whose reference name is ref name. 


to octal word W, decimal bit B of 


reference name is ref_name. 


same as 


same as 


ref name$W(0). 


ref _name$0(0). 


entry pt in 


entry pt in 


entry pt in 


entry pt in 


entry pt in 


segment whose 
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segno:W(B) points to octal word W, decimal bit B of segment whose 
octal segment number is segno. 


segnoiW same as segno;W(0). 
segno} same as segno;0(0). 
segno same as segno;j0(0). 
segnojentry pt points to word identified by entry point entry pt in 


segment whose octal segment number is segno. 


A null pointer is represented by the virtual pointer 7777711, by -111, or by -1. 
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Name: cv_rcep attributes _ 


The cv_rcep attributes subroutine contains several entry points that are 
useful in manipulating RCP resource attribute specifications and descriptions. 


RCP resource attribute descriptions are printable strings that describe the 
attributes of resources (devices and volumes). For a description of the syntax 
of attribute descriptions see the Multics Administrators' Manual Project, Order 
No. AK51. 


RCP resource attribute specifications are encoded representations of 
attribute descriptions. They may be either absolute, relative, or multiple. An 
absolute attribute specification represents a complete and consistent state of 
all the attributes of a resource. A relative attribute description represents a 
desired modification to the state of all the attributes of a resource, and must 
be applied to an absolute attribute specification to produce the desired change 
in that absolute specification. A multiple attribute specification does not 
represent a consistent state of all the attributes of a resource at any given 
time, but is useful for representing the union of all such consistent states, 
i.e., potential attributes. 


Entry: cv_rep attributes $to_ string 


This entry point takes an RCP resource attribute specification and produces 
a printable RCP attribute description. 


Usage 


declare cv rcp attributes $to string entry (char (*), bit (72) 
dimension (2), char (*) varying, fixed bin (35)); 


call ecv_rep attributes $to string (type, attributes, string, code); 


where: 
aie type (Input) 
specifies the type of resource from which attributes was obtained 
e.g., tape, disk drive (see "Notes" below). 
25 attributes (Input) 
is an RCP attribute specification (sees "Notes" below). 
3. string (Output) 
is a printable RCP attribute description. 
4, code (Output) 


is a standard status code. 
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Notes 


A list of defined resource types may be obtained via the list _resource types 
command. 
% 


Entry: cv _rep_ attributes $from string 


This entry point accepts a printable RCP attribute description and produces 
an RCP attribute specification. 


Usage 


declare cv rep attributes $from_ string entry (char (*), bit (72) 
dimension (2), char (*)varying, fixed bin (35)); 


call cv_rep attributes $from_ string (type, attributes, String, code); 


where: 
Te type (Input) 
specifies the type of resource to which attributes applies. 
2. attributes (Output) 
is the same as above. 
ce string (Input) 
is the same as above. 
4. code (Output) 


is the same as above. 


Entry: ev_rep attributes $modify 


This entry point applies a printable RCP resource attribute description 
(representing a relative attribute specification) to a given resource specification 
and returns a new attribute specification as the result. The resulting attribute 
specification consists of the original attribute specification, modified by the 
attributes specified in the printable description. 
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Usage 


declare cv rep attributes $modify entry (char (*), bit (72) dimension (2), 
char (*)varying, bit (72) dimension (2), fixed bin (35)); 


call cv_rep attributes $modify (type, attributes, string, new_attributes, 


code); 
where: 
T type — (Input) 
specifies the type of resource to which attributes and string apply. 
2% attributes (Input) 
is an absolute RCP attribute specification. 
35 string (Input) 
is a printable RCP attribute description that is to modify 
attributes. 
4, new_attributes (Output) 
is the new absolute RCP attribute specification. 
De code (Output) 


is the same as above. 


Entry: cv_rep attributes $from_string rel 


This entry point generates a relative attribute specification that can later 
be applied to attribute specifications of specific resources via the 
ev_rep attributes $modify_ rel entry point. 


Usage 


declare cv_rep attributes $from_string rel entry (char (*), 
char (*)varying, bit (72) dimension (4), fixed bin (35)); 


call cv_rep attributes $from_string rel (type, string, rel attributes, 


code); 
where: 
I type (Input) 
specifies the type of resource to which string applies. 
2. string (Input) 
is a printable RCP attribute description. 
3. rel attributes (Output) 


is the relative RCP attribute specification. 
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a code (Output) 
is the same as above. 


Entry: cv_rep attributes $modify rel 


This entry point applies a relative attribute specification produced by the 
ev_rep attributes $from_ string rel entry point to an absolute attribute 
specification of a specific resource. 


Usage 
declare cv_rcep attributes $modify rel entry (bit (72) dimension (2), 
bit (72) dimension (4), bit (72) dimension (2)); 


call cv_rep attributes $modify rel (attributes, rel attributes, 
new attributes); 


where: 
1 attributes (Input) 
is an absolute attribute specification. 
2. rel attributes (Input) 
is a relative attribute specification to be applied to attributes. 
3. new attributes (Output) 
is the resulting absolute attribute specification. 
Notes 


The caller must ensure that attributes and rel _ attributes refer to the same 
resource type, i.e., were generated by previous calls to cv_rep attributes_ 
where the type arguments were identical. 


Entry: cv_rep attributes $reduce implications 


This entry point accepts an attribute specification for a volume and 
returns the necessary minimal attribute specification that a device must possess 
to be able to accept the volume. 


Usage 


declare cv_rep attributes $reduce implications entry (char (*), bit (72) 
dimension(2), char (*), bit (72) dimension (4), fixed bin (35)); 
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call cv_rep attributes $reduce implications (vol type, vol attributes, 
dev type, dev_attributes, code); 


where: 
Ty vol type (Input) 
specifies the type of volume from which vol attributes was obtained. 
2 vol attributes (Input) 
is an absolute attribute specification for the volume type 
specified. 
3. dev_ type (Output) 
is the resource type of the device that accepts the given volume 
type. 
4, dev_attributes (Output) 
is a minimal relative attribute specification for a device capable 
of accepting a volume with the given attributes. 
5. code (Output) 


is the same as above. 


Entry: cv_rep attributes $protected change 


This function entry point accepts an absolute attribute specification for a 
resource and arelative attribute specification which is to modify it. It 
returns a value expressing whether or not this modification would affect 
protected attributes of the resource. No modification is actually attempted by 
this entry. 


Usage 
declare cv_rcep attributes $protected change entry (bit (72) dimension(2), 
bit (72) dimension(4)) returns (bit (1) aligned); 


protected change = cv_rep attributes $protected change (attributes, 
rel_ attributes); 


where: 
1. attributes (Input) 
is an RCP attribute specification. 
2% rel attributes (Input) 
is a relative attribute specification to be applied to ettributes. 
3. protected change (Output) 


is "1"b if this operation would modify protected attributes of the 
resource; otherwise, it is "O"b. 
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> cv _rep attributes $test valid 
This. entry point is used to determine whether a given attribute 
fication is absolute, relative, multiple, or invalid. 


declare cv_rep attributes $test_ valid entry (char(*), bit 72 dimension (2), 
fixed bin, fixed bin (35)); 


call cv_rep attributes $test_valid (type, attributes, validity, code); 


type (Input) . 
specifies the type of resource to which attributes applies. 


attributes (Input) 
is an RCP attribute specification. 


validity (Output) 
shows whether the attribute specification is absolute, relative, or 
multiple. 
0 is an absolute attribute specification 
1 is a relative attribute specification 
2 is a multiple attribute specification 


code (Output) 
is a standard status code. 
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Name: cv_userid_ 


The cv_userid subroutine converts a character string containing an 
abbreviated User_id into one containing all three components, i.¢€. 
Person id.Project_id.tag. 


Usage 


declare cv_userid_ entry (char(*)) returns (char(32)); 


user_id = ecv_userid (string); 


where: 


Ves string (Input) 
is the abbreviated User id. 


Zs user_id (Output) 
is a User_id containing all three components. 


Notes 


The Person id, Project_id and tag components are truncated to 20, 9 and 1 
characters, respectively. An asterisk ("*") is supplied for missing components. 


Examples 
Abbreviated User id Full User_id 
Smith.Project.a Smith.Project.a 
Smith.Project Smith.Project.* 
Smith Smith.*.* 
-Project *,Project.* 
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Name: decode descriptor_ 


The decode descriptor subroutine extracts information from argument 
descriptors. It should be called by any procedure wishing to handle variable 
length or variable type argument lists. It processes the descriptor format used 
by PL/I, BASIC, COBOL, and FORTRAN. For a list of the type codes used, see 
"Argument List Format" in Section 2 of this manual. 


Usage 


declare decode descriptor_ entry (ptr, fixed bin, fixed bin, 
bit(1) aligned, fixed bin, fixed bin, fixed bin); 


call decode descriptor. (ptr, n, type, packed, ndims, size, scale); 


where: 
Ty ptr (Input) 
points either directly at the descriptor to be decoded or at the 
argument list in which the descriptor appears. 
2 n (Input) 
controls which descriptor is decoded. If n is 0, ptr points at the 
descriptor to be decoded; otherwise, ptr points at the argument 
list header and the nth descriptor is decoded. 
3s type (Out put) 
is the data type specified by the descriptor. Type codes appearing 
in an old form of descriptor are mapped into the new codes. 
0 is returned if an invalid type code is found in the old format 
descriptor 
-1 is returned if descriptors are not present in the argument list 
or if the nth descriptor does not exist 
Ny packed (Out put ) 
describes how the data is stored. 
new format descriptors 
eT" data is packed 
"oO" data is not packed 
old format descriptors 
ey data is a string 
a 8 al & data is not a string 
5. ndims (Output) 


indicates either the number of dimensions of tne descriptor array or 
whether the descriptor is an array or a scalar. 


new format descriptor 
n descriptor is an array of n dimensions 
0 descriptor is a scalar 


old format descriptor 


1 descriptor is an array 
0 deseriptor is a scalar 
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T- 


size 


scale 


(Out put ) 
is the arithmetic precision, string size, or number of structure 
elements of the data of the new format descriptor. This value is 0 
if an old form of descriptor specifies a structure. 


(Out put) 


is the scale of an arithmetic value for a new format descriptor. 
This value is O for an old form of descriptor. 


7-44 AK92 


define area_ define area 


Name: define area_ 


The define _area_ subroutine is used to initialize a region of storage as an 
area and to enable special area management features as well. The region being 
initialized may or may not consist of an entire segment or may not even be 
specified at all, in which case a segment is acquired (from the free pool of 
temporary segments) for the caller. 


See the release area subroutine for a description of how to free up 
segments acquired via this interface. 


Usage 


declare define area_ entry (ptr, fixed bin(35)); 


eall define_area_ (info ptr, code); 


where: 
Te info ptr (Input) 
~ points to the information structure described in "Notes" below. 
ae code (Output) 
is a system status code. 
Notes 


The define _area_ subroutine gives the user more control over an area than 
is defined in the PL/I language. The PL/I empty built-in function cannot empty 
a define area area; the release area subroutine must be used instead. PL/I 
offset values and PL/I area assignment cannot be used with extensible areas. In 
PL/I, an area variable is always initialized. Consequently, if a based area is 
overlayed upon arbitrary storage instead of being allocated with a PL/I allocate 
statement, then the define _area_ subroutine must be used to turn the contents of 
the based area into a PL/I area value. 


The structure pointed to by info_ptr is the standard area_info structure 
used by the various area management routines and is described by the following 
PL/I declaration defined by the system include file, area_info.incl.pl1: 
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define area_ 


del 1 area_info aligned based, 
2 version fixed bin, 
2 control, 
3 extend bit(1) unaligned, 
3 zero on alloc bit(1) unaligned, 
3 zero on free  bit(1) unaligned, 
3 dont_free bit(1) unaligned, 
3 no freeing bit(1) unaligned, 
3 system bit(1) unaligned, 
3 pad bit(30) unaligned, 
2 owner char(32) unaligned, 
2 n components fixed bin, 
2 size fixed bin(30), 
2 version of area fixed bin, 
2areap — pers 
2 allocated blocks fixed bin, 
2 free blocks fixed bin, 
2 allocated words fixed bin(30), 
2 free words fixed bin(30); 
where: 
1. version 
is to be filled in by the caller and should be 1. 
2. control 
are control flags for enabling or disabling features of the area 
management mechanism. 
3. extend 
indicates whether the area is extensible. This feature should only 
be used for per-process, temporary areas. 
"4 Mb yes 
NONh no 
4, zero _on alloc 
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indicates whether blocks are cleared (set to all zeros) at 
allocation time. 

14h yes 

noth no 


zero_on free 


dont _fr 


no_ free 


indicates whether blocks are cleared (set to all zeros) at free 
time. 

"41th yes 

n"ONb no 


ee 
indicates whether the free requests are disabled, thereby not 
allowing reuse of storage within the area. 


nIw> yes 
"OMb no 
ing 


indicates whether the allocation method assumes no free requests 
will ever be made for the area and that, hence, a faster allocation 
Strategy can be used. 

wath yes 

"ONb no 
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16. 


17. 


18. 
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system 


is used only by system code and indicates that the area is managed 
by the system. 


"1"Db yes 

"O"b no 
pad 

is not used and must be all zeros. 
owner 


is the name of the program requesting that the area be defined. 
This is needed by the temporary segment manager. 


n_components 
is the number of components in the area. (This item is not used by 
the define_area_ subroutine.) 


size 
is the size, in words, of the area being defined. The minimum size 
is thirty-two (decimal) words. The maximum size is the maximum 
number of words in a segment. 


version of_area 
is 1 for current areas and 0 for old-style areas. (This item is not 
used by the define _area_ subroutine.) 


areap 
is a pointer to the region to be initialized as an area. If this 
pointer is null, a temporary segment is acquired for the area and 
areap is set as a returned value. If areap is initially nonnull, it 
must point to a O mod 2 address. 


allocated blocks 
is the number of allocated blocks in the entire area. (This item is 
not used by the define _area_ subroutine.) 


free_blocks 
is the number of free blocks in the entire area (not counting virgin 
storage). (This item is not used by the define_area_ subroutine.) 


allocated words 
is the number of allocated words in the entire area. (This item is 
not used by the define_area_ subroutine.) 


free words 


is the number of free words in the entire area. (This item is not 
used by the define _area_ subroutine.) 
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Name: dial manager 


The dial manager subroutine is the user interface to the answering service 
dial facility. The dial facility allows a process to communicate with multiple 
terminals at the same time. This subroutine uses a structure, dial manager arg, 
to receive arguments from its caller. This structure is described below, under 
~tNotes". For more information, see the description of the dial command in the 
MPM Commands. 


The dial_manager_ subroutine uses an event channel to communicate with the 
answering “service. This event channel is specified by 
dial manager arg.dial channel. The channel must be created by the caller. The 
answering service sends notices of dial connections and hangups over this channel. 
The dial manager subroutine goes blocked on the event-wait channel awaiting a 
response to the request from the answering service. When the user program receives 
wakeups over this channel, it should call the convert dial message subroutine 
to decode the event message. a > = 


The dial manager $allow dials and dial manager $registered server’ entry 
points establish a dial Ling. “The dial id specified in 
dial manager arg.dial qualifier is used as the first argument to the dial command 
when connecting a terminal to a process. The dial id may be an alphanumeric 
string from 1 to 12 characters long. The dial id "system" and "s" are reserved 
for the Initializer process. A process can have only one dial line active at a 
time. 


Entry: dial manager $aliow dials 


This entry point requests that the answering service establish a dial line 
to allow terminals to dial to the calling process. The caller must set 
dial manager _arg.dial qualifier to the dial _id for the dial line. The caller 
must also set dial manager __ arg.dial channel to an event-wait channel in the caller's 
process. After fhe dial manager fallow dials entry point has been called, the 
event channel may be changed to an event-call channel. To connect a terminal to 
the process, the User id of the process must be specified as the second argument 
of the dial command. If the process has already established another dial line, 
the request is rejected and code is set to error table fdial active. 


Usage 
declare dial manager $allow dials entry (ptr, fixed bin(35)); 


call dial manager $allow dials (request ptr, code); 


where: 

1s request ptr (Input) 
is a pointer to the dial manager arg structure described in "Notes" 
below. —- = 


2s code (Output) 
is a standard status code. 
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Entry: dial manager $registered_ server 


This entry point is used to request that the answering service establish a 
dial line to allow terminals to dial to the calling process using only the dial 
qualifier. The calling process must have rw access to the access control segment 
dial.<dial qualifier>.acs in >sce1>rep if this request is to be honored. If the 
process has already established a dial line, the request is rejected and code is 
set to error table $dial_active. 


Usage 


declare dial manager _$registered_server entry (ptr, fixed bin(35)); 


call dial manager $registered_ server (request ptr, code); 


where the arguments are the same as for the dial manager $allow dials entry 
point. 


Entry: dial manager $dial_out 


This entry point is used to request that an auto call channel be dialed to 
a given destination and, if the channel is successfully dialed, that the channel 
be assigned to the requesting process. The ealler must set 
dial manager arg.dial out destination to the telephone number to be dialed. The 
callér must also set dial manager arg.dial channel to an event-wait channel in 
his process. The answering service sends notice of dial completions and hangups 
over this channel. After the dial manager $dial out entry point has been called 
the event channel may be changed to an event-call channel. The user programs 
receiving the wakeup should cali the convert dial message subroutine to decode 
the event message. The caller may set dial manager arg.channel name to the name 
of a specific channel to be used. It is also possible to set 
dial manager arg.channel name to a starname, in which case the answering service 
chooses a channel that has a matching name and has all the attributes specified 
in dial manager arg.reservation string. The name of the chosen channel is not 
returned by dial manager ; it must be obtained via a call to convert dial message . 


XN 


Usage 


declare dial manager $dial out entry (ptr, fixed bin(35)); 


call dial manager $dial_ out (request ptr, code); 


where the arguments are the same as for the dial manager $allow dials entry 
point. ~ 
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Entry: dial_manager_$release_channel 


This entry point is used to request the answering service to release the 
channel specified in channel name. This channel must be dialed to the caller at 
the time of this request. The caller must set dial _manager_arg.dial_ channel to 

| an event wait channel in the caller's process. The caller also must set 
dial_manager_arg.channel_name to the name of the channel to be released. The 
user must make dial _manager_ arg.dial channel an event-wait channel before using 
this call. If the Channel Was dialed, the channel is returned to the answering 
service and another access request may be issued. If the channel is a slave 
channel, the channel is hung up. 


Usage 


declare dial_manager $release_ channel entry (ptr, fixed bin(35)); 


call dial_manager_$release_channel (request_ptr, code); 


where the arguments are the same as for the dial_manager_$allow_dials entry 
point. 


Entry: dial manager $release channel no hangup 
entry = = oe ne 


This entry point performs the same function as the 
dial_manager_$release channel entry point except that slave channels are not 
hung up. 


f Entry: dial_manager_$release_no_ listen 


This entry point requests the answering service to release the channel 
specified in channel_name, which must have been attached by means of the 
dial anager _ $tandd attach entry point. The channel is left in a hung-up state 
and is not available for use until an explicit "attach" operator command is 
issued for the channel. This entry point has the same requirements as the 
dial_manager_$release_ channel entry point. 


[ Usage 
I declare dial_manager_$release no listen entry (ptr, fixed bin (35)); 
I call dial_manager $release_no listen (request ptr, code); 


| where the arguments are the same as for the dial_ manager _$release channel entry . 
point. 
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Entry: dial_manager $shutoff dials 


This entry point informs the answering service that the user process wishes 
to prevent further dial connections, and that existing connections should be 
terminated. The same information should be passed to this entry point as was 
passed to the dial _ manager $allow_dials or dial _ manager $registered_server entry 
point. The dial_channel must be an event-wait channel. 


Usage 


declare dial_manager $shutoff_dials (ptr, fixed bin(35)); 


call dial_manager $shutoff_dials (request_ptr, code); 


where the arguments are the same as for the dial_manager $allow_ dials entry 
point. 


Entry: dial_manager $release dial id 


This entry point functions as does dial _ manager $shutoff_ dials, except that 
dialed terminals are not hung up. The user can later release dialed terminals 
by a call to dial_ manager $shutoff dials or by calls to 
dial manager $release channel. 


Usage 


declare dial manager $release_dial_id (ptr, fixed bin (35)); 


call dial_manager $release dial_id (request_ptr, code); 


where the arguments are the same as for the dial manager $shutoff_dials entry 
point. 


Entry: dial_manager_ $privileged_attach 


This entry point allows a privileged process to attach a "slave" channel. 
The effect is as if that terminal had dialed to the requesting process. The 
caller must set all variables required by the dial_manager_$allow_dials entry 
point and then must set dial _manager_arg.channel name to the name of the channel 
that is to be attached; dial manager arg.dial qualifier is not used and should 
be set to the null string. This must be the same name as' specified by the 
channel master file. The slave service type must be specified for this channel 
in the channel master file. The calling process must have rw access to the 
access control segment <channel_name>.acs in >sel>rep if this request is to be 
honored. 
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Usage 


declare dial_manager $privileged attach entry (ptr, fixed bin(35)); 


call dial_manager $privileged attach (request ptr, code); 


where the arguments are the same as for the dial_manager_ $allow_dials entry 
point. 


I Entry: dial_manager_$tandd_attach 


This entry point allows a process with appropriate access to attach any 
communications channel that is in the channel master file and not already in 
use, for the purpose of performing online testing of the channel. The 
requesting process acquires the channel in a hung-up, nonlistening state. The 
channel can be released using either the dial manager _$release channel or the 


dial_manager $release no listen entry point. In the latter case, the channel 
will be unavailable to users until the operator enters an attach command for the 
channel. The caller must set all the variables required by the 


dial _ manager $privileged attach entry point; dial_manager arg.dial qualifier is 
not used and should be set to the null string. 


| Usage 
I declare dial_manager $tandd_attach entry (ptr, fixed bin (35)); 
I call dial manager $tandd_ attach (request ptr, code); 


| where the arguments are the same as for the dial _ manager $allow dials entry 
point. 


| Access Required 


>scl>rep>CHAN NAME.acs, where CHAN NAME is the name of the channel to be 


| The caller must have at least rw access to both >scl>rep>tandd.acs and 
attached. 


Entry: dial_manager_$terminate dial out 


This entry point is used to request that the answering service hang up an 

* auto call line and unassign it from the requesting process. The caller must set 

dial _manager_arg.channel_ name to the name of the channel being used; 

| channel _name cannot be null. The caller also must set 
dial _manager_arg.dial channel to an event-wait channel. 
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Usage 


declare dial_manager_$terminate dial out entry (ptr, fixed bin(35)); 


call dial_manager_$terminate dial out (request ptr, code); 


where the arguments are the same as for the dial_manager $allow_dials entry 
point. 


Notes 


The first argument in all of the calls (request ptr) is a pointer to the 
dial _manager_arg structure. This structure is used to pass ae variety of 
information to the dial manager _ subroutine. It is declared in 
dial _manager_arg.incl.pli. It has the following declaration: 


del 1 dial_manager arg aligned, 

2 version fixed bin initial (2), 
2 dial qualifier ehar (22), 

2 dial channel fixed bin (71), 

2 channel name ehar (32), 

2 dial out destination char (32), 

2 reservation string ehar (256), 

2 dial_message fixed bin (71); 

where: 


1. version 
indicates the version of the structure that is being used. This is 
set by the caller and must be 2. 


2. dial qualifier 
is the dial qualifier for calls to the dial manager $allow dials, 
dial_manager_$registered_server, dial_manager $shutoff dials, and 
dial manager $release dial id entry points. This field should be 
set te blanks if it is not used. 


3. dial channel 
is an interprocess communication channel used to receive messages 
from the answering service. The channel must always be an 
event-wait channel at the time a call to any dial_manager_ entry is 
made. 
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4, channel name 

is used for calls to the dial_manager_$terminate dial out and 
dial manager $release channel entry points to indicate which channel 
should De disconnected. In calls to the 
dial_manager $privileged attach entry point, it indicates which 
channel should be attached. In calls to the dial manager $dial out 
entry point, it indicates which auto_call channel should be used for 
a dial-out attempt. For this entry, the following convention is 
observed: the caller can fully specify a channel name or can use 
the star convention to specify a group of channels from which the 
answering service is to pick one. A channel _ value of ™" (null 
string) is equivalent to "**"; other examples of acceptable values 
are: "a.h*¥.*" and "a.¥.¥%,co". (Consult the MPM Reference Guide for 
a description of the star convention.) This field should be set to 
blanks if it is not used. 


Di dial _out_destination 

is used for calls to the dial manager $dial out entry point. 
Interpretation of this value is determined by the multiplexer that 
controls the channel being dialed out. The standard FNP multiplexer 
interprets this value as a telephone number and ignores all 
characters except decimal digits and the exclamation point (!). It 
recognizes "I" as a dial-tone-wait character and will suspend 
dialing until the autocall unit receives a dial tone. Any number of 
de characters can exist in a dial _out_destination, and _ the 
standard FNP multiplexer will pause at each. This field should be 
set to blanks if it is not used. 


is used to specify the desired characteristics of a channel in calls 
to the dial _manager_$dial_ out entry. The reservation string (which 
can be null), consists of reservation attributes separated by 
commas. The channel used by a dial-out operation must have the 
characteristics specified in the reservation string. Reservation 
attributes consist of a keyword and optional argument. Attributes 
allowed are: 


baud _rate=BAUD RATE 
line type=LINE TYPE 


The attribute name, such as "baud rate", must appear literally in 
the string. BAUD RATE is a decimal representation of the desired 
channel line speed and must appear in a baud rate attribute. 
LINE TYPE is a valid line type, chosen from line types.incl.pl1 and 
must appear in aline type attribute. Examples: "baud rate=300, 
line type=ASCII", "line type=BSC". This field should be set to 
blanks if it is not used or no particular channel attributes are 
required. 


ie dial_message (Output) 

is a copy of the dial message received from the answering service. 
The dial manager_ subroutine makes an answering service request 
based upon the arguments supplied by its caller; it then waits for a 
reply from the answering service. This reply is converted using 
convert dial _ message _, and some of the results of the conversion are 
immediately available to dial_manager_ callers as output arguments. 
To obtain other portions of the dial message absorbed by 
dial_manager_, the user must call convert dial_message_ specifying 
the value of this field. This field is set to -1 if an error occurs 
in the dial _ manager _ or answering service request; 
convert dial _ message rejects attempts to convert such a message 
with the return code error_table$badcall. 


6. reservation string 
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dial manager _ dial_manager_ 


The second argument in all calls (code) is an error status indicator. It 
can assume any value documented in the convert dial message description 
(earlier in this manual), or one of the following: 


error table $bad_conversion 
a reservation string value (BAUD RATE) was not a proper decimal value. 


error_table $invalid line type 
the value of LINE TYPE is not acceptable. 


error table $bad_arg 
reservation string contains an unrecognized attribute. 
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Name: dl_handler_ 

This subroutine has three entry points that issue queries for each of three 
situations involving deletion. These situations are: 

1a Deletion of an entry whose safety switch or copy switch is on. 

ae Deletion via a starname that matches all entries, e.g. "**¥", 

3% Deletion of a directory (delete dir always queries). 
This subroutine returns a status code depending on the user's answer. If the 


user answers "yes", all three entry points turn off the safety and copy 
Switches, and in the case of a directory, set sma to the user before returning. 


Entry: dl handler_ 

This entry point, called when an entry has its safety switch or copy switch 
on, issues a query of the form: 

<caller>: <path> is protected. Do you want to delete it? 


If the user answers yes, dl_handler_ turns off both switches and returns a zero 
status code. 


Usage 


del dl_handler_ entry (char(*), char(*), char(*), fixed bin(35)); 


call di_handler_ (caller, dn, en, code); 


where: 
Dis caller (Input) 
is the name of the calling program, used to print the query. 
26 dn (Input) 
is the directory name. 
ce en (Input) 
is the entry name. 
4, code (Output) 
is a standard status code. It may be: 
0 


if the user has answered "yes", switches have been turned off 
and the entry can now be deleted 
error table $action_not_performed 
if the user answered "no" 
other codes 
mean that the switches could not be turned off 


7/81 7-54 AK92C 


dl handler_ dl handler _ 


The two other entry points have the same calling sequence as di handler . 


Entry: dl handler $dblstar 


This entry point issues the query: 

Do you want to '<caller> <en>' in <dn>? 
where caller, the name of the calling program, is assumed to be a suitable verb. 
This entry point is called, for example, by the delete and unlink commands, 


which also pass a double starname as en: 


Do you want to 'delete **' in <dir path>? 
Do you want to ‘unlink **' in <dir_ path>? 


Entry: dl handler $dirdelete 


This entry point assumes it is given a directory pathname, and issues the 
query: 
<caller>: Do you want to delete the directory dn>en? 


This entry point is called, for example, by the delete dir command. 
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Name: dprint_ 


This subroutine contains several entry points used to submit requests to | 
the I/O daemon for printing or punching of segments and multisegment files. 


i 
Entry: dprint_ 7 i 
This entry point adds a request to print or punch a segment or multisegment 
file to the specified queue. 
Usage 
declare dprint_ entry (char(*), char(*), ptr, fixed bin(35)); 
call dprint_ (dir_name, entryname, dprint_arg_ ptr, code); | 
where: 
1 dir_name (Input) 
is the absolute pathname of the containing directory. | 
2. entr yname (Input) 
is the entry name of the segment, multisegment file, or link to the §! 
segment or multisegment file to be printed or punched. I 
3. dprint_arg ptr (Input) 
is a pointer to the dprint_arg structure (described in "Notes" 
below) that defines the options for this request. If this pointer 
is null, the default settings are used for all options. 
uy code (Output) 
is a standard status code. 
Notes 


The dprint_ subroutine uses the following structure, defined in the system 
include file dprint_ arg.incl.pli, to determine the details of the request. If 
ho structure is supplied, default values are used. 


del 1 dprint_arg based aligned, 

2 version fixed bin, 
2 copies fixed bin, 
2 delete fixed bin, 
2 queue fixed bin, 
2 pt_pch fixed bin, 
2 notify fixed bin, 
2 heading char (64), 

2 output_module fixed bin, 
2 dest char(12), 
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MM MM PM NM MPP DP /P— fo 


where: 


1. 


WI 


7/82 


version 


copies 


delete 


queue 


pt_pceh 


notify 


heading 


dprint_ 


earriage control, 

3nep | bit(1) unaligned, 
3 single bit(1) unaligned, 
3 non edited bit(1) unaligned, 
3 truncate bit(1) unaligned, 
3 center top label bit(1) unaligned, 
3 center bottom label bit(1) unaligned, 
2mbz1 — ~ bit(30) unaligned, 
mbz2(30) fixed bin(35), 
forms char(8), 

lmargin fixed bin, 

line lth fixed bin, 

class char(8), 

page lth fixed bin, 

top label char(136), 

bottom label char(136), 

bit count fixed bin(35), 
form name echar(24), 
destination char(24), 

chan stop path char( 168), 
request type char(24)unaligned; 


is the version number of the structure. This is set by the caller 
and must be the value of the named constant dprint arg version 6 
also defined in the include file. a 


is the number of copies requested. (The default is 1.) 


indicates whether the segment is to be deleted after printing or 
punching. 

1 deletes the segment 

0 does not delete the segment (default) 


is the priority queve in which the request is placed. (The default 
is the default queue for the default print/punch request type and is 
site-defined). 


indicates whether the request is for printing, punching, or plotting. 
1 print request (default) 

2 punch request 

3 plot request 


indicates whether the requestor is to be notified when the request 
is completed. 

1 notifies the requestor 

0 does not notify the requestor (default) 


is the string to be used as a heading on the front page of the 
output. If it is a null string, the’ requestor's Person id is used. 
(The default is the null string.) 
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@. output module 
indicates the I/O module to be used in executing the request. 


Al indicates printing (default) 
2 indicates 7-punching 
3 indicates Multics card code (mec) punching 
4 indicates "raw" punching 
5 indicates plotting 
9. dest 
is not used. See destination below. 
10. nep 


indicates whether no-endpage mode is used. 
"qth yes : 
7OND no (default) 


11. Single 
indicates whether single mode, which causes all vertical tabs and 
new pages to be converted to new lines, is used. 

ee Bia 8, yes 

"OND no (default) 


12. non edited 
oo indicates whether nonedited mode, which causes all nonprinting control 
characters and non-ASCII characters to be printed as octal escape 
sequences, is used. 
tah yes 
WOrD no (default) 


12. truncate 
indicates whether truncate mode is used. 
"qth yes 


"Oo"h no (default) 


14. center top label 
“indicates whether the top label should be centered. 
hiMb Wee 
OMS no (default) 


15. center bottom label 
indicates whether the bottom label should be centered. 
WTE"b yes 
"O"b no (default) 


16. mbz1 
is not used and should be set to (30)"0"b. 


17. mbz2 
is not used and should be set to zeros. 


18. forms 
is not used. 


19. IlImargin 
indicates the left margin position. (The default is 0.) 


20. line 1th 
indicates the line length. (The default is -1, which implies maximum 
line length.) 


21. class 
is not used. See request type below. 
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22. page lth 
‘indicates the page length, i.e., the number of lines per logical 
page. (The default is -1, which implies the physical page length.) 


23. top label 
is a label to be placed at the top of every page. (The default is 
the null string.) 


24. bottom label 
is a label to be placed at the bottom of every page. (The default 
is the null string.) 


25. bit_count 
is the segment bit count. 


26. form_name 
is the name of special forms needed. 


27. destination 
is the string to be used to indicate where the output should be 
delivered. If it is null, the requestor's Project_id is used. The 
default is the null string. 


28. chan_stop path 
is the path of user channel stops. 


29. request type 

Is the request type name to be used to queue the request. If 
printing is requested, the request type must be of the generic type 
"printer"; if punching is requested, the request type must be of 
generic type "punch." (The default request type for printing is 
"printer"; the default for punching is "punch.") 


} Entry: dprint_$check_daemon_access 


This entry point checks the I/0 daemon's access to a given segment or 
multisegment file. It returns whether the daemon responsible for a given 
request type has "r" access to the file and "s" access to the containing 
directory and whether the I/0 daemon coordinator can delete the file if 
requested. 


| Usage 


declare dprint_$check daemon_access entry (char(*), char(*), char(*), 
bit(1) aligned, bit(1) aligned, bit(1) aligned, char(*), 
fixed bin(35)); 

call dprint_$check_daemon_access (dirname, entryname, request type, 
delete permission, read_permission, status_permission, driver_userid, 
code); 
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where: 

Ts dirname (Input) 
is the absolute pathname of the containing directory. 

2. entryname (Input) 
is the entry name of the segment, or multisegment file, or a link to 
the segment or multisegment file for which the daemon's access is to 
be checked. 

as request type (Input) 


is the name of the request type in which a request to print or punch 
the file will be placed. The access of the driver process for this 
request type will be returned. 


4, delete permission (Output) 
indicates whether the I/0 coordinator has sufficient access to 
delete the file if requested. The coordinator requires "m" access 
to the containing directory to delete the file. 


5. read permission (Output) 
indicates whether the driver process of the given request type has 
"r" access to the given segment or multisegment file. 


6. status permission (Output) 
indicates whether the driver process of the given request type has 
"s" access to the directory containing the segment or multisegment 
file. 


7.  driver_userid (Output) 
is the name of the process that processes requests for the specified 
type. This value is in the form "Person_id.Project_id.*". 


8. eode (Output) 
is a standard system status code. 


Notes 


The user must have "s™ access to the directory containing the segment or 
multisegment file to determine whether the driver has read access to the file. 


The user must have "s" access to the directory containing the directory 
containing the segment or multisegment file in order to determine whether the 
I/O coordinator can delete the file and whether the driver process has "s" 
access to the containing directory. 
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] Entry: dprint $queue_ contents 


H This entry point returns the number of requests in a specific I/O daemon 
I] queue. 
| Usage 
declare dprint $queue_contents entry (char(*), fixed bin, fixed bin, 
fixed bin(35)); 
] call dprint $queue contents (request type, queue, n_requests, code); 
] where: 
| i request type (Input) 
is the name of the request type whose queue is to be checked. 


ae queue (Input/Output) 
is the number of the queue to be examined. If -1 is specified, the 
default queue of the given request type is checked and the number of 
the default queue is returned in this parameter. 


| 3. n_requests (Output) 
is the number of requests in the specified queue. 


| 4, code (Output) 
is a standard system status code. 
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Name: dump _segment_ 


This subroutine prints the dump of a segment formatted in the same way as 
the dump segment command (MPM Commands) would print it. The output format is 
controlled by a bit string that allows most of the formatting control arguments 
available to dump segment. 


Usage 


declare dump segment_ entry (ptr, ptr, fixed bin, fixed bin(18), 
fixed bin(18), bit(*)); 


call dump segment _ (iocb ptr, first, block size, offset, count, format); 


where: 

1. iocb_ptr (Input) 
is a pointer to the I/O control block that specifies where the dump 
is to be written. 

2. first (Input) 
is a pointer to the first word of the data to be dumped. 

3. block size (Input) 
is the number of words in the block if blocked output is desired. 
If unblocked output is desired, this is zero. 

4, offset (Input) 
is an arbitrary offset to be printed in addition to the address of 
the first word of data to be dumped if the offset option in the 
format string is specified. (It is reset to this initial value at 
the start of each block.) 

oe count (Input) 
is the number of words to dump, starting with the word pointed to by 
FIrst:. 

6. format (Input) 


is a format control bit string with the following definition: (See 
the dump segment documentation, MPM Commands, for a full discussion 
of these arguments.) 


bit definition default value 
1 address column on 
2 offset column off 
3 short off 
4 bed off 
5 ascii off 
6 long off 
T ebcdic9 Orr 
8 ebcdic8 off 
9 Ubit off 
10 hex8 off 
11 hex 9 off 
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Name: ebcdic_ to ascii_ 


The ebedic to ascii subroutine performs isomorphic (one-to-one reversible) 
conversion from EBCDIC to ASCII. The input data is a string of valid EBCDIC 
characters, A valid EBCDIC character is defined as a 9-bit byte with a 
hexadecimal value in the range 00 < hex value < FF (octal value in the range 
000 < oct_value < 377). = 7 


Entry: ebedic_to_ascii_ 


This entry point accepts an EBCDIC character string and generates an ASCII 
character string of equal length. 


Usage 


declare ebcdic_to_ascii_ entry (char(*), char(*)); 


call ebedie to_ascii_ (ebedic in, ascii_out); 


where: 
Vs ebcdic_in (Input) 

is the string of EBCDIC characters to be converted. 
P. ascii_out Out put) 


( 
is the ASCII equivalent of the input string. 


Entry: ebcdic to _ascii_$ea_ table 


This entry point defines the 256-character translation table used to 
perform conversion from EBCDIC to ASCII. Of the 256 valid EBCDIC characters, 
only 128 have ASCII equivalents. These latter 128 characters are defined in the 
Isomorphic ASCII/EBCDIC Conversion Table (in the ascii to ebedic subroutine 
description.) For defined characters, the mappings implemented by the 
ebedic to_ascii_ and ascii_to_ebedic subroutines are isomorphic; i.e., each 
character has a unique mapping, and mappings are reversible. An undefined (but 
valid) EBCDIC character is mapped into the ASCII SUB (substitute) character, 
octal 032; the mapping of such a character is anisomorphic. The result of 
converting an invalid character is undefined. 


Usage 


declare ebcdic to ascii $ea_table char(256) external static; 
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Note 


Calling the ebcdic _to_ascii_ subroutine is extremely efficient, since 
conversion is performed by a Singie MVT instruction and the procedure runs in 
the stack frame of its caller. 
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Name: execute epilogue | 


The execute epilogue subroutine is called during process or run unit 
termination to call the routines in the list of epilogue handlers. The logout 
and new_proc commands are the prime callers of execute epilogue . It is also 
called when the run unit terminates to allow programs executing in the run unit 
to clean up. The add_epilogue handler _ subroutine is used to add a program to 
the list that execute epilogue calis. 


Usage 


declare execute epilogue entry (bit (1) aligned); 


call execute_epilogue (run only); 


where run_only (Input) is set to "1"b if epilogue handlers are to be invoked 
only for the run unit and not for the entire process. 
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Name: find condition frame_ 


This subroutine returns a pointer to the most recent condition frame, or 
the most recent one before a specified frame. 


Usage 


del find condition frame_ entry (ptr) returns (ptr); 


stack ptr = find condition frame_ (start_ptr); 


where: 

ss start ptr (Input) 
is a pointer to a stack frame. The most recent condition frame 
before this stack frame is returned. The start ptr argument can be 
obtained by another call to find condition frame . If start ptr is 
null, the most recent condition frame is returned. 

2% stack ptr (Output) 
is a pointer to the desired condition frame. 

Note 

ne condition history can be traced by repeated calls tO 


find condition frame _, starting with a null start ptr argument and repeatedly 
passing the output stack ptr as input. 
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Name: find condition info_ 


This subroutine, given a pointer to a stack frame being used when a signal 
occurred, returns information relevant to that condition. 


Usage 


declare find condition info _ entry (ptr, ptr, fixed bin(35)); 


call find condition _info_ (stack ptr, condition _info ptr, code); 


where: 


ie stack ptr (Input) 
is a pointer to a stack frame being used when a condition occurred. 
It is normally the result of acall to find_condition frame ; if 
null, the most recent condition frame is used. 


ea condition info ptr (Input) 
is a pointer to the structure (see "Notes" below) in which 
information is returned. 


3. code (Output) 
is the standard status code. It is nonzero when the stack ptr 
argument does not point to a condition frame or, if the stack ptr 
argument is null, when no condition frame can be found. 


Notes 


The structure that condition info ptr points to is declared in the include 
file condition info.incl.pl1. It is declared as: 


del 1 condition info aligned based (condition info ptr), 
2 me ptr ptr, 
2 version fixed bin, 
2 condition name char(32) varying, 
2 info ptr ptr, 
2 we ptr ptr, 
2 loc ptr ptr, 
2 flags unaligned, 
3 crawlout bLECT), 
3 padi bit(35), 
2 pad2 bit(36), 
2 user_loc ptr ptr, 
2 pad3 (4) bit (36); 
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where: 


Vy 


10. 


me ptr 
if not null, points to the machine conditions. Machine conditions 
are described in the MPM Reference Guide. 

version 
is the version number of this structure. It should be set to 
condition info version 1. This variable is declared in 
condition info.inel.pl1. 

condition name 


is the condition name. 


info _ptr 
points to the info structure if there is one; otherwise, it is null. 
The info structures for various system conditions are described in 
the MPM Reference Guide. 


we ptr 
7 is a pointer to machine conditions describing a fault that caused 
control to leave the current ring. This occurs’ when the condition 
described by this structure was signalled from a lower ring and, 
before the condition occurred, the current ring was left because of 
a fault. Otherwise, it is null. 


loc ptr 
is a pointer to the location where the condition occurred. If 
crawlout is "1"b, this points to the last location in the current 
ring before the condition occurred. 


crawlout 
indicates whether the condition occurred ina lower level ring in 
which it could not be adequately nhandied. 


"OD no 

"4th yes 
pad] 

is currently unused and should be set to "0O"b. 
pad2 


is currently unused and should be set to "O"b, 


user loc ptr 
is a pointer to the most recent nonsupport location before the 
condition occurred. If the condition occurred in a_ support 
procedure (e.g., a PL/I support routine), it is possible to locate 
the user call that preceded the condition. 


pad3 
is currently unused and should be set to "0O"b. 
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Name: get _default_wdir_ 


The get_default _wdir_ function returns the pathname of the user's current 
default working directory. 


Usage 


declare get _default_wdir_ entry returns (char(168) aligned); 


default _wdir = get_default_wdir_ (); 


where default_wdir (Output) is the pathname of the user's current default 
working directory. 
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Name: get definition_ 


The get_definition_ subroutine returns a pointer to a specified definition 
within an object segment. 


Usage 


declare get_definition_ entry (ptr, char(*), char(*), ptr, fixed bin(35)); 


call get_definition_ (def_section_ ptr, segname, entryname, def ptr, code); 


where: 
Ns def section ptr (Input) 
is a pointer to the definition section of the object segment. This 
pointer can be obtained via the object _info_ subroutine. 
2 segname (Input) 
is the name of the object segment. 
3. entryname (Input) 
is the name of the desired entry point. 
4, def ptr (Out put) 
is a pointer to the definition for the entry point. 
5. eode (Out put) 


is a standard status code. If the entry point is found, code is 0. 
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Name: get _entry_arg descs_ 


This subroutine returns information about the calling sequence of a 
procedure entry point. 


Entry: get_entry_arg descs_ 


This entry point, given a pointer to the entry sequence or segdef of a 


procedure entry point, returns a list of argument descriptors describing the 
parameters of the entry point. 


Usage 


declare get_entry_arg_deses_ entry (ptr, fixed bin, (*) ptr, fixed 
bin(35) )5 


call get_entry arg descs_ (entry ptr, nargs, desc ptrs, code); 


where: 
is entry ptr (Input) 
points to the entry sequence or segdef of the procedure entry point 
whose parameter descriptors are to be described. 
Px nargs (Output) 
is the number of parameters declared in the procedure entry point. 
33 desc ptrs (Output) 
is an array of pointers to the argument descriptors describing the 
declared parameters of the entry point. If dimension (dese ptrs, 1) 
is less than nargs, the pointers identify the first dimension 
(desc ptrs, 1) parameter descriptors. 
4, code (Output) 
is a standard status code. It may be: 
error table $nodescr 
the entry point did not have parameter descriptors. 
Notes | 


For some version 0 object segments, a code of zero is returned, nargs is i 
set, but the descriptor pointers in dese _ptrs are null. 
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Entry: get_entry_ arg descs $info 


This entry point, given a pointer to tne entry sequence or segdef of a 
procedure entry point, returns a list of argument descriptors describing the 


parameters of the entry point, plus a_ set of entry sequence flags which further 
describe the entry point. 


Usage 
declare get_entry_arg descs $info entry (ptr, fixed bin, (*) ptr, ptr, 
fixed bin(35)); 


call get_entry arg descs $info (entry ptr, nargs, desc _ptrs, 
entry _desc_info_ptr, code); 


are as described above. 


4, entry desc info ptr (Input) 
points to the structure described under "Notes" below. 


ae code (Output) 
is as described above. 


Notes 


The entry desc_info_ptr argument of get_entry arg descs _$info points to the 
structure shown below. This structure is declared in entry_ desc_ info.inel.pl4. 


del 1 entry desec_info aligned based(entry dese _info_ptr), 
2 version fixed bin, 
2 flags, 


(3 basic indicator, 


3 revision 1, 

3 has descriptors, 

3 variable, 

3 function) bit(1) unaligned, 
3 pad bit(13) unaligned, 


entry _desc_info_version_1 fixed bin int static 
options(constant) init(1), 
entry _desc_info ptr ptr: 
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where: 
Ne version 
is the version number of this structure. The current version 
number is 1. The named constant, entry desc_info_version 1 
should be used to set this version number. 
2's flags 
are the flags which further describe the procedure entry point. 
3. basic indicator 
is on if the entry point is in a program written in the BASIC 
language. 
4. revision 1 


is on if the entry sequence has version 1 descriptor data. 


on has descriptors 
is on if the entry sequence has argument descriptors describing 
its parameters. 


6. variable 

is on if the entry point accepts an undefined number of 
arguments, and has been declared with the opticons(variable) 
attribute. This flag will usually be off for entry points in 
command and active function procedures, even though these 
procedures accept a variable number of arguments. Command and 
active function procedures usually do not declare their entry 
points with explicit parameters or with the options(variable) 
attribute. 


re function 
is on if the procedure entry point is a function which returns 
a value. The final parameter argument descriptor describes 
this return value. 


8. entry desc _ info _version_1 
is anamed constant which the caller should use to set the 
version number in the structure above. 


9. entry desc _ info ptr 
points to the structure above. 


Entry: get _entry arg descs $text only 


This entry point, given a pointer to the entry sequence of a procedure 
entry point, returns a list of argument descriptors describing the parameters of 
the entry point. It differs from the get_entry_arg descs_ entry point, in that 
it assumes that it is given a pointer to an entry sequence in the text section 
of the procedure, rather than checking to see if it was given a pointer to a 
segdef. 
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Usage 


declare get_entry_ arg descs $text_only entry (ptr, fixed bin, (*) ptr, 
fixed bin(35)); 


call get_entry_arg descs $text only (entry ptr, nargs, dese ptrs, code); 


where the arguments are the same as for the get_entry_arg_ descs_ entry point 
above. If entry ptr does not point to an entry point in the text section, then 
error_table $nodescr is returned as the value of code. 


Entry: get _entry arg descs $text_only_info 


Th.s entry point, given a pointer to the entry sequence of a procedure 
entry point, returns a list of argument descriptors describing the parameters of 
the entry point, plus a set of entry sequence flags which further describe the 
entry point. It differs from the get_entry_arg descs $info entry point, in that 
it assumes that it is given a pointer to an entry sequence in the text section 
of the procedure, rather than checking to see if it was given a pointer to a 


segdef. 


Usage 


declare get_entry_ arg deses $text only info entry (ptr, fixed bin, (*) ptr, 
ptr, fixed bin(35)); 


call get_entry_arg_descs $text only info (entry ptr, nargs, desc ptrs, 
entry desc info ptr, code); - ~ 7 


where the arguments are the same as for the get _entry_arg descs $info entry 
point above. 
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Name: get _entry name_ 


The get entry _name_ subroutine, given a pointer to an externally defined 
location or entry point in a segment, returns the associated name. 


Usage 


declare get_entry name_ entry (ptr, char(*), fixed bin(18), char(8) aligned, 
fixed bin(35)); 


call get_entry_name_ (entry ptr, symbolname, segno, lang, code); 


where: 

13 entry ptr (Input) 
is a pointer to a procedure entry point. 

2. symbolname (Out put) 
is the name corresponding to the location specified by entry ptr. 
The maximum length is 256 characters. 

3 segno (Out put) 
is the segment number of the object segment where symbolname is 
found. It is useful when entry ptr does not point to a text 
section. 

4, lang (Output) 
is the language in which the segment or component pointed to by 
entry ptr was compiled. 

oe code (Output) 


is a standard status code. 
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Name: get entry point _del_ 


The get_entry_ point del _ subroutine returns attributes needed to construct 
a PL/I declare Statement for external procedure entry points and for 
error table codes and other system-wide external data. The program obtains the 
attributes from data files declaring all unusual procedure entry points (e.g., 


ALM segments), from system-wide data values sys info$max seg size), and from the 
argument descriptors describing the entry point's parameters that are included 
with the entry point itself. 


Entry: get entry point del_ 


This entry point returns the declaration for an external value, either from 
one of the data files, or by using the parameter argument descriptors associated 
with the procedure entry point. It makes a special case of error table values 
by always returning 'fixed bin(35) ext static' for them. For example, given the 
name iox_ $put_chars, it might return: 


entry (ptr, ptr, fixed bin(21), fixed bin(35)) 


Note that neither the name of the external value nor any trailing semicolon (;) 
is returned as part of the declaration. 


Usage 


del get_entry_point_del_ entry (char(*), fixed bin, fixed bin, 
char(*) varying, char(32) varying, fixed bin(35)); 


call get_entry point _del_ (name, del_style, line length, dcl, type, code); 


where: 

1. name (Input) 
is the name of the external entry point or data item whose 
declaration must be obtained. 

2. del style (Input) 
is the style of indentation to be performed for the name. See 
"Notes" below for a list of allowed values. 

3. line length (Input 

- is the maximum length to which lines in return value are allowed to 

grow when indentation is performed. 

4, del (Output) 


is the declaration that was obtained. 
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5. type (Output) 
is the type of declaration. In the current implementation, this is 
always a null string. 


om code (Output) 
is a standard status code describing any failure to obtain the 
declaration. 


Notes 


Three styles of declaration indentation are supported by the dcel_style 
argument described above. Style 0 (dcl_style = 0) involves no indentation. The 
declaration is returned as a single line. 


Style 1 (del_style = 1) indents the declaration in the format similar to 
the indent command. Long declarations are broken into several lines. For 
example, a declare statement for hcs $initiate_ count would appear as: 


del hes $initiate count entry (char(*), char(*), char(*), fixed bin(24), 
fixed bin(2), ptr, fixed bin(35)); 


when the string "del hes $initiate_ count" is concatenated with the value 
returned by get_entry_point_del_, and a semicolon (;) is appended to this value. 


Style 2 (del style = 2) indents the declaration in an alternate format that 
makes the name of the entry point stand out from its declaration. It assumes 
that the name of the entry point begins in column 11 (indented one horizontal 
tab stop from left margin), and the declaration begins in column 41. In style 
2, the declare statement for hes $initiate count would appear as: 


del hes $initiate count entry (char(*), (char(*), (char(*), 
fixed bin(24), fixed bin(2), ptr, 
fixed bin(35)); 


Most command and active function entry points do not declare arguments in 
their procedure statements since they accept a variable number of arguments. 
Neither do they use the options(variable) attribute in their procedure 
statements. Therefore, when get entry point del encounters’ a procedure entry 
point with no declared arguments and without options(variable), it assumes the 
options(variable) attribute required for commands and active functions and 
returns: 


entry options(variable) 
It distinguishes between such assumed options(variable) entries and those that 
explicitly use the options(variable) attribute in their procedure statement by 
returning "entry" for the assumed case and "entry()" for the explicit case. 
Thus, for the display_entry point del command, which explicitly uses 
options(variable) in its procedure statement, get_entry_point_del_ returns: 


entry() options(variable) 
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Search List 


The get_entry point _del_ subroutine uses the "declare" search list, which 
has the synonym "del", to find data files describing unusual procedure entry 
points. For more information about search lists, see the descriptions of the 
search facility commands and, in particular, the add search paths command 
description (in the MPM Commands). Type: 

print_search paths declare 


to see what the current declare search list is. The default search list 
identifies the data file: 


7sss>pll.del 


User-Provided Data Files 


Users may provide data files that redeclare standard system entry points 
(e.g., redeclaring a subroutine as a function), or that declare their own entry 
points or external data items. The add search paths command can be used to 
place user-provided data files in the "declare" search list. For example: 


add_search paths declare [hd]>my_ pl1.del -first 


Declarations have the general form of: 
virtual _entry declaration 
For example: 
ioa_ entry options(variable) 
Note that the word "del" is not ineluded in the data item, nor does the 
declaration end with a semicolon (;). External data values are declared in a 


similar fashion. For example: 


iox_$user output ptr external static 
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Name: get equal name_ 


The get_equal_ name _ subroutine accepts an entryname and an equai name as 
its input and constructs a target name by substituting components or characters 
from the entryname into the equal name, according to the Multics equal 
convention. Refer to "Constructing and Interpreting Names" in Section 3 of the 
MPM Reference Guide for a description of the equal convention and for the rules 
used to construct and interpret equal names. 


Usage 


declare get_equal_ name_ entry (char(*), char(*), char(32), fixed bin(35)); 


call get _equal_name_ (entryname, equal name, target_name, code); 


where: 
Ase entryname (Input) 
is the entryname from which the target is to be constructed. 
Trailing blanks in the entryname character string are ignored. 
2s equal_name (Input) 
is the equal name from which the target is to be constructed. 
Trailing blanks in the equal name character string are ignored. 
3. target_name (Output) 
is the target name that is constructed. 
4, code (Output) 
is a standard status code. It can be one of the foilowing: 
error table $bad_equal name 
the equal name has a bad format 
error table $badequal 
there is no letter or component in the entryname_ that 
corresponds to a percent character (%) or an equal sign (=) in 
the equal name 
error table $longeql 
the target name to be constructed is longer than 32 characters 
Notes 


If the error_table $badequal status code is returned, then a target name is 
returned in which null character strings are used to represent the missing 
letter or component of entryname. 


If the error_table $longeql status code is returned, then the first 32 
characters of the target name to be constructed are returned as target name. 


The entryname argument that is passed to get_equal_ name _ can also be used 
as the target name argument, as long as the argument has a length of 32 
characters. 
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Entry: get _equal name $component 


This entry point accepts an archive and component name and two equal names 
as input and constructs a target archive and component name by substituting 
components or characters from the archive and component names into the equal 
names, according to the Multics archive component pathname equal convention. 
Refer to "Archive Component Pathnames and Equal Names" in the MPM Reference 
Guide for a description of the convention. 


Usage 
declare get _equal_ name _$component entry (char(*), char(*), char(*), 
char(*), char(32), char(32), fixed bin(35)); 


call get_equal_ name $component (entryname, component, equal _entryname, 
equal _ component, target_entryname, target component, code); 


where: 

Ts entryname (Input) 
is the archive name from which the target archive name is 
constructed, or is the entryname from which the target component 
name is constructed if the source pathname is not an archive 
component pathname. 

2. component (Input) 
is the component name from which the target component name is 
constructed or is anull string if the source pathname is not an 
archive component pathname. 

3. equal _entryname (Input) 
is the equal name from which the target archive name is constructed 
or is the equal name from which the target entryname is constructed 
if the target pathname is not an archive component pathname. 

4, equal component (Input) 
is the equal name from which the target component name is 
constructed or is a null string if the target pathname is not an 
archive component pathname. 

or target _entryname (Output) 


is the target archive name that is constructed or is the target 
entryname that is constructed if the target pathname is not an 
archive component pathname. 


Os target component (Output) 


is the target component name that is constructed or is a null string 
if the target pathname is not an archive component pathname. 
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Ts code (Output) 

is a standard status code. It can be one of the following: 

error table $bad_ equal name 
either | equal entryname or equal_component has a bad format. 

error table _ $badequal 
there is no letter or component in the archive or component 
name that corresponds te a percent character (%) or an equal 
sign (=) in the appropriate equal name. 

error_table $longeql 
the target archive or component name to be constructed is 
longer than 32 characters. 

error table $no archive for equal 
the target pathname has an equal name in the archive name 
position but the source pathname is not an archive component 
pathname. 


Notes 


If the error_table $badequal status code is returned, the name returned in 
the appropriate output argument is constructed using null character strings to 
represent the letters or component names missing from the source name. 


If the error table $longeql status code is returned, the first 32 
characters of the constructed name are returned in the appropriate output 
argument. 


The two pairs of input arguments to this subroutine are expected to be the 
output arguments from two calls to expand pathname $component, one call for the 
source pathname and one for the pathname containing the equal names. 


The output arguments of this subroutine should be used in a call to the 
initiate file $component subroutine documented in MPM Subroutines. For example: 


call expand pathname _$component (arg1, source dir, source ename, 
source comp, code); 
if code “= 0 then... 


call expand pathname $component (arg2, target_dir, equal _entry, 
savas component, code); 
if code “= 0 then ... 


call get_equal_name_$component (source _ename, Source comp, equal entry, 
equal component, target ename, target_comp, code); 


a 


if code *= 0 then ... 


call initiate file $component (source dir, source _ename, source comp, 
R ACCESS, source ptr, source bit count, ~eode); 
if code “= 0 then see 


call initiate file $component (target _dir, target _ename, target_comp, 


R_ ACCESS, target _ptr, target_ bit_count, code); 
if code “= 0 then 0% 
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Name: get_external variable 


The get external variable subroutine obtains the location and size of an 
external variable. 


Usage 


declare get external variable entry (char(*), ptr, fixed bin(19), ptr, 
fixed bin(35)); 


call get external variable (vname, vptr, vsize, vdese ptr, code); 


where: 

Ts vname (Input) 
is the name of the external variable. 

2. vptr (Output) 
is a pointer to the current allocation of the external variable. 

3. vsize (Output) 
is the size (in words) of the external variable. 

h, vdese ptr (Output) 
is a pointer to a standard argument descriptor array describing the 
external variable. If the external variable does not have 
descriptor information associated with it, a null pointer is 
returned. 

5. code (Output) 


is a standard status code. 
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Name: get lock id_ 


The get lock id subroutine returns the 36-bit unique lock identifier to be 
used by a process in setting locks. By using this lock identifier, a convention 
can be established so that a process wishing to lock a data base and finding it 
already locked can verify that the lock is set by an existing process. 


Usage 


declare get_lock_id_ entry (bit(36) aligned); 


call get_lock_id_ (lock id); 


where lock_id (Output) is the unique identifier of this process used in locking. 
For a more detailed discussion of locking see the set_lock_ description in the 
MPM Subroutines. ~ 
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Name: get privileges_ 


The get privileges _ function returns the access privileges of the process. 
WA 


(See Access Control" in Section VI of the MPM Reference Guide for more 
information on access privileges.) 


Usage 


declare get privileges entry returns (bit(36) aligned); 


privilege string = get_privileges (); 


where privilege string (Output) is a bit string with a bit set ("i"b) for each 
access privilege the process has. 


Notes 


The individual bits in privilege string are defined by the following PL/I 
structure: : 


del 1 privileges unaligned, 
2 ipe bitCT), 
2 dir bit(1), 
2 seg bit(1), 
2 soos bit(1), 
2 ring bit(1), 
2 rep jon i oa Gb a 
2 mbz bit(30); 
where: 
1 ipe 
indicates whether the access isolation mechanism (AIM) restrictions 
for sending/receiving wakeups to/from any other process are bypassed 
for the calling process. 
Wqth yes 
"ONb no 
2. dir 
indicates whether the AIM restrictions for accessing any directory 
are bypassed for the calling process. 
"4b yes 
"ONb no 
3 seg 


indicates whether the AIM restrictions for accessing any segment are 
bypassed for the calling process. 

ak a © yes 

woth no 
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SOOS 


ring] 


rep 


mbz 


indicates whether the AIM restrictions for accessing directories 
that have been set security-out-of-service are bypassed for’ the 
calling process. 

With yes 

NnONh no 


indicates whether the AIM restrictions for accessing any ring 1 
system segment are bypassed for the calling process. 

"7Mb yes 

"ONb no 


indicates whether the AIM restrictions for accessing resources 
through RCP resource management are bypassed for the calling 
process. 

W4Mbh yes 

"orb no 


is unused and is "0"b, 
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Name: get_ring_ 


The get_ring function returns to the caller the number of the protection 
ring in which the caller is executing. For a discussion of rings’ see 
"Intraprocess Access Control" in Section 6 of the MPM Reference Guide. 


Usage 


declare get_ring entry returns (fixed bin(3)); 


ring _no = get_ring_ (); 


where ring _no (Output) is the number of the ring in which the caller is 
executing. 
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Name: get _system_free_area_ 


The get_system_free_area_ function returns a pointer to the system free 
area for the ring in which it was called. Allocations by system programs are * 
performed in this area. 


Usage 


declare get_system_free_area_ entry returns (ptr); 


area_ptr = get_system_free area_ (); 


where area ptr (Output) points to the system free area. 
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Name: hash index _ 


The hash index function returns the value of a hash function of a character 
string. ~ ~ ca 4 


Usage 


declare hash index entry (ptr, fixed bin(21), fixed bin, fixed bin) 
returns (fixed bin); 


hash value = hash index (string ptr, String len, mbz, table size); i 
where: 
1. string ptr (Input) 


is a pointer to the character string to be hashed. This character 
string must be aligned. 


2. string len (Input) 
~ is the length of the character string. 


3. mbz (Input) 
is reserved and must be zero. 


4, table size (Input) 
~ ds the number of entries in the hash table. 


Notes 


The value returned is between zero and tabie size-i, inclusive. 
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Name: hes $add_dir_inacl_entries 


-- The hes $add_dir_inacl_entries entry point adds specified directory access 
modes to the initial” access control list (initial ACL) for new directories 
created for the specified ring within the specified directory. If an access 
name already appears on the initial ACL of the directory, its mode is changed to 
the one specified by the call. 


Usage 


declare hes $add dir inacl entries entry (char(*), char(*), ptr, fixed bin, 
fixed Bin(3), fixed bin(35)); 


call hes $add dir_ inacl_ entries (dir _name, entryname, acl ptr, acl]_ count, 
ring, code); 


where: 
as dir_name (Input) 
is the pathname of the containing directory. 
2. entr yname (Input) 
is the entryname of the directory. 
3.  acl_ptr (Input) 
points to a user-filled dir_acl structure. See "Notes" below. 
4, acl] count (Input) 
contains the number of initial ACL entries in the dir_acl structure. 
See "Notes" below. 
54 ring (Input) 
is the ring number of the initial ACL. 
6. code (Output) 


is a storage system status code. 


T-T2 AKQ2 


hes $add dir_inacl_ entries hes $add dir inacl entries 


Notes 


The following structure is used for dir acl: 


del 1 dir_acl (acl_count) aligned based (acl ptr), 
2 access name Char(32), 
2 dir modes bit(36), 
2 status code fixed bin(35); 


where: 


1s access name 
is the access name (in the form Person id.Project id.tag) that 
identifies the processes to which this initial ACL entry applies. 


2. dir modes 
contains the directory modes for this access name. The first three 
bits correspond to the status, modify, and append modes. The remaining 
bits must be O's. For example, Status permission is expressed as 
"100"b. The access mode values.incl.pl1 include file defines mnemonics 
for these bit strings: 


del (S ACCESS init ("100"b), 
M ACCESS init ("010"b), 
A ACCESS init ("001"b), 
SK ACCESS init ("101"b), 
SM ACCESS init ("110"b) 
SMA ACCESS tnt. C8111") ) 


bit (3) internal static options (constant); 
3. status code 


“is a storage system status code for this initial ACL entry only. 


If code is returned as error table fargerr, then the erroneous initial ACL 
entries in the dir acl structure have status code set to an appropriate error 
code. No processing is performed in this instance. 
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Name: hes $add_inacl entries 


The hes $add_inacl_entries entry point adds specified access modes to the 
initial access control list (initial ACL) for new segments created for the 
specified ring within the specified directory. If an access name already 
appears onthe initial ACL of the segment, its mode is changed to the one 
Specified by the call. 


Usage 


declare hes $add inacl_entries entry (char(*), char(*), ptr, fixed bin, 
fixed bin(3), fixed bin(35)); 


» 


call hes $add_inacl_ entries (dir_name, entryname, acl_ptr, acl count, ring, 


code); 
where: 
13 dir_name (Input) 
is the pathname of the containing directory. 
23 entryname (Input) 
is the entryname of the directory. 
3. acl _ ptr (Input) 
points to a user-filled segment_aci structure. See "Notes" below. 
4, acl_count (Input) 
contains the number of initial ACL entries in the segment_acl 
structure. See "Notes" below. 
5 ring (Input) 
is the ring number of the initial ACL. 
6. code (Output) 


is a storage system status code. 
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Notes 


The following structure is used for segment acl: 


del 1 segment_acl (acl_count) aligned based (acl ptr), 
2 access name char (32), 
2 modes bit(36):, 
2 zero_pad bit(36) 
2 status_code fixed bin(35); 
where: 
io access name 


is the access name (in the form Person_id.Project_id.tag) that 
identifies the processes to which this initial ACL entry applies. 


an modes 
contains the modes for this access name. The first three bits 
correspond to the read, execute, and write modes. The remaining 
bits must be O's. For example, rw access is expressed as "101"b. 
The access mode values.incl.pl1 include file defines mnemonics for 
these values: 


del (N_ACCESS init ("000"b), 
R ACCESS init ("100"b), 
E ACCESS init ("010"b), 
W ACCESS init ("001"b), 
RE ACCESS init ("110"b) 
REW ACCESS init ("111"b), 
RW ACCESS init ("101"b)) 


bit (3) internal static options (constant); 


3. zero_pad 
must contain the value zero. (This field is for use with extended 
access and may only be used by the system.) 


H, status code 


is a storage system status code for this initial ACL entry only. 


if code is returned as error table $argerr, then the erroneous initial ACL 
entries in segment _acl have status code set to an appropriate error code. No 
processing is performed in this instance. 
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Name: hes $del_dir_tree 


The hes $del dir tree entry point, given the pathname of a_ containing 
directory and the entryname of a_ subdirectory, deletes the contents of the 
subdirectory from the storage system hierarchy. All segments, links, and 
directories inferior to that subdirectory are deleted, including the contents of 
any inferior directories. The subdirectory is not itself deleted. For 
information on the deletion of directories, see the description of the 
hes $delentry file entry point in the MPM Subroutines. 


Usage 


declare hcs_ $del_dir_tree entry (char(*), char(*), fixed bin(35)); 


call hes $del_dir_tree (dir_name, entryname, code); 


where: 
1. dir_name (Input) 
is the pathname of the containing directory. 
2. entryname (Input) 
is the entryname of the directory. 
3. code (Out put) 
is a storage system status code. 
Notes 


The user must have status and modify permission on the subdirectory and the 
safety switch must be off in that directory. If the user does not have status 
and modify permission on inferior directories, access is automatically set and 
processing continues. 


If an entry in an inferior directory gives the user access only in a ring 
lower than his validation level, that entry is not deleted and no further 
processing is done on the subtree. For information about rings, see 
“Intraprocess Access Control" in Section 6 of the MPM Reference Guide. 
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Name: hes $delete dir_inacl entries 


The hes $delete dir _inacl_ entries entry point is used to delete specified 
entries from an initial access control list (initial ACL) for new directories 
created for the specified ring within the specified directory. The delete acl 
structure used by this subroutine is described in the hes $delete_inacl_ entries 
entry point. 


Usage 
declare hes $delete dir_inacl_entries entry (char(*), char(*), ptr, 
fixed bin, fixed bin(3), fixed bin(35)); 


call hes $delete_dir_inacl_ entries (dir_name, entryname, acl _ptr, 
acl count, ring, code); 


where: 
1. dir_name (Input ) 
is the pathname of the containing directory. 
2. entryname (Input) 
is the entryname of the directory. 
3s acl_ ptr (Input) 
points to the user-filled delete acl structure as described in the 
hes $delete inacl_ entries entry point. 
us acl_count (Input) 
is the number of initial ACL entries in the delete acl structure. 
5. ring (Input) 
is the ring number of the initial ACL. 
6. code (Out put ) 
is a storage system status code. (Output) 
Notes 


If code is returned as error_table $argerr, then the erroneous initial ACL 
entries in the delete acl structure have status code set to an appropriate error 
code. No processing is performed in this instance. 


If an acceSs name in the delete_acl structure cannot be matched to one 
existing on the initial ACL, then the status code of that initial ACL entry in 
the delete acl structure is set to error table $user not found. Processing 
continues to the end of the delete acl structure and code is returned as 0. 
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Name: hes $delete_inacl entries 


The hes $delete _inacl_entries entry point is called to delete specified 
entries from an initial access control list (initial ACL) for new segments 
created for the specified ring within the specified directory. 


Usage 
declare hes $delete_inacl_entries entry (char(*), char(*), ptr, fixed bin, 
fixed bin(3), fixed bin(35)); 


eall hes $delete_inacl_entries (dir_name, entryname, acl ptr, acl_count, 
ring, code); 


where: 
1. dir_name (Input) 
is the pathname of the containing directory. 
2% entryname (Input) 
is the entryname of the directory. 
ie acl_ ptr (Input) 
points to the user-filled delete _acl structure. See "Notes" below. 
4, acl_ count (Input) 
contains the number of initial ACL entries in the delete acl 
structure. See "Notes" below. 
ae ring (Input) 
is the ring number of the initial ACL. 
6. code (Output) 
is a storage system status code. 
Notes 


The following is the delete acl structure: 


del 1 delete_acl (acl_count) aligned based (acl_ptr), 


2 access name char (32), 
2 status_code fixed bin(35); 
where: 
ds access name 
is the access name (in the form of Person_id.Project_id.tag) that 
identifies the initial ACL entry to be deleted. 
2. status_code 


is a storage system status code for this initial ACL entry only. 
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If code is returned as error table $argerr, then the erroneous initial ACL 
entries in the delete acl structure have status code set to an appropriate error 
code. No processing is performed in this instance. 


If an access name in the delete acl structure cannot be matched to one 
existing on the initial ACL, then the Status code of that initial ACL entry in 
the delete_acl structure is set to error_ table $user_ not_found. Processing 
continues to the end of the delete acl structure and code is returned as 0. 
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Name: hes $force write 


The hes $force write entry point causes the supervisor to force modified 
pages out of main memory. 


Usage 


declare hes $force write entry (ptr, bit(36), fixed bin(35); 


call hes $force write (segp, flags, code); 


where: 
| ta segp (Input) 

is a pointer to the segment whose modified pages are to be written. 

| 2. flags (Input) 

specify a set of options. Currently, only one option is defined. 

The following structure (also defined in the system include file 

force write flags.incl.pl1) defines the options: 

declare 1 force write options based (addr (flags)) unaligned, 

2 mbz1 bit(1), 
2 serial write DILCt); 
2 mbz2 bit(34); 

serial write: 

OID queue write requests for all modified pages in parallel, up 
to the maximum permitted by the supervisor's force-write 
limit (see shes $set_ force write limit). 

hd Dea 9) queue write requests for all modified pages serially; one at 
a time. 

mbz1 

mbz2 
these fields must be zero. 

| 3. code (Output) 
is a standard status code. 
Notes 


Use of this entry point may introduce substantial real time delay into 
execution, since the caller must wait for the movement of the disk; other usage 
of the system, meanwhile, may cause further delay. 


This entry point protects data against an unrecoverable main memory crash. 
On systems with bulk store paging devices, this subroutine may flush pages to 
the bulk store, which is recoverable in case of main memory crashes, rather than 
to the disk. 
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This entry point returns the following non-zero status codes. If the 
segment is an inner ring segment, error table $bad ring brackets is returned. 
If the user does not have write access to the segment, error table $moderr is 
returned. If the segment is not known, not active, or a hardcore segment, then 
error table $invalidsegno is returned. Because the user has no control over 
whether or not the segment is active, error _ table $invalidsegno should not be 
treated as an error. 
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Name: hes $get_ author 


The hes $get_author entry point returns the author of a segment, directory, 
multisegment file, or link. 


Usage 


declare hes $get_author entry (char(*), char(*), fixed bin(1), char(*), 
fixed bin(35)); 


call hes $get_author (dir_name, entryname, chase, author, code); 


where: 

qs dir_name (Input) 
is the pathname of the containing directory. 

ex entryname (Input) 
is the entryname of the segment, directory, multisegment file, or 
link. 

3. chase (Input) 
if entryname refers to a link, this flag indicates whether to return 
the author of the link or the author of the segment, directory, or 
multisegment file to which the link points. 
0 return link author 
1 return segment, directory, or multisegment file author 

4, author (Out put) 
is the author of the segment, directory, multisegment file, or link 
in the form of Person_id.Project_id.tag with a maximum length of 32 
characters. An error is not detected if the string, author, is too 
Short to hold the author. 

Be code (Output) 
is a storage system status code. 

Note 


The user must have status permission on the containing directory. 
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Name: hes $get_be_author 


The hes $get_be author entry point returns the bit count author of a 


segment or directory. The bit count author is the name of the user who last set 
the bit count of the segment or directory. 


Usage 


declare hes $get_bc_author entry (char(*), char(*), char(*), 
fixed bin(35)); 


call hes $get_be_ author (dir_name, entryname, be_author, code); 


where: 

Ns dir_name (Input) 
is the pathname of the containing directory. 

2% entryname (Input) 
is the entryname of the segment or directory. 

3. be_author (Output) 
is the bit count author of the segment or directory in the form of 
Person_id.Project_id.tag with a maximum length of 32 characters. An 
error is not detected if the string, be_author, is too short to hold 
the bit count author. 

y, code (Output) 
is a storage system status code. 

Note 


The user must have status permission on the containing directory. 
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Name: hes $get_dir_ring brackets 


The hes $get_dir_ring brackets entry point, given the pathname of a 
containing directory and the entryname of a_ subdirectory, returns the value of 
that subdirectory's ring brackets. 


Usage 


declare hes $get_dir_ring brackets entry (char(*), char(*), 
(2) fixed bin(3), fixed bin(35)); 


call hes_ $get_dir_ring_ brackets (dir_name, entryname, drb, code); 


where: 

13 dir_name (Input) 
is the pathname of the containing directory. 

2. entryname (Input) 
is the entryname of the subdirectory. 

3.  drb (Out put) 
is a two-element array that contains the directory's ring brackets. 
The first element contains the level required for modify and append 
permission; the second element contains the level required for 
status permission. 

u, code (Output) 
is a storage system status code. 

Notes 


The user must have status permission on the containing directory. 


Ring brackets are discussed in "Intraprocess Access Control" in Section 6 
of the MPM Reference Guide. 
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Name: hes $get_ exponent control 


This entry point returns the current settings of the flags that control the 
system's handling of exponent overflow and underflow conditions. For more 
information on exponent control see the description of 
hes $set_exponent control. 


Usage 


declare hes $get_ exponent control entry (bit(1) aligned, bit(1) aligned, 
float bin(63)); 


call hes $get_exponent control (restart_underflow, restart_overflow, 
overflow value); 


where: 

1. restart_underflow (Output) 
is "1"b if underflows are currently being automatically restarted, 
and "O"b otherwise. 

2. restart_overflow (Output) 
is "i"b if overflows are currently being automatically restarted, 
and "0O"b otherwise. 

3. overflow _value (Output) 
is the value used for the result of the computation in the case of 
overflow. 


7/81 7-83.1 AK92C 


hes $get_ips_mask hes $get_ips_ mask 


Name: hes $get_ips mask 


The hes $get_ips mask entry point returns the value of the current ips 
mask. 


Usage 


ee 


declare hes $get_ips_mask entry (bit(36) aligned); 


call hes $get_ips_ mask (old_mask); 


where: 
ee old_mask (Output) 

is the current value of the ips mask. 
Notes 


A "1"b in any position in the mask means that the corresponding ips 
interrupt is enabled. 


The thirty-sixth (rightmost) bit ef old_mask does not correspond to an 
interrupt, but is used as aocontrol bit, giving a positive indication that a 
particular masking or unmasking operation has taken place. No ips interrupts 
ean occur in the time interval between the requested mask modification and the 
returning of the old_ mask, with the control bit set appropriately. 


Entry points used at the beginning of a critical section of code, to 
disable some or all ips interrupts, return a value of "1"b for the control bit, 
while those that are used at the end of a critical section of code, to re-enable 
those interrupts, return a value of "0O"b for the control bit. Thus, a condition 
handler can interpret a value of "1"b in the control bit as meaning that 
execution was in a critical section of code, and the ips mask has been modified. 
See "Notes" in the description of the hes $set_ automatic ips mask entry point 
for information about the state of the ips mask immediately after an ips 
interrupt occurs. 


The control bit in the mask returned by this entry point is always "O"b. 
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Name: hes $get_link_ target 


The hes $get_link target entry point returns the pathname of the ultimate 
target of a link if the ultimate target exists, or what that pathname would be 
if the target did exist. 


Usage 
declare hes $get_link target entry (char(*), char(*), char(*), char(*), 
fixed bin(35)); 


call hes $get_ link target (dir_name, entryname, link dir_name, 
link _entryname, code); 


where: 

1. dir_name (Input) 
is the directory name containing the link. 

2. entryname (Input) 
is the entryname of the link for which target information is 
desired. 

3. link_dir_name (Output) 
is the directory name of the link target with a maximum length of 
168 characters. 

4, link_entryname (Output) 
is the entryname of the link target with a maximum length of 32 
characters. 

5s code (Output) 
is a standard status code. 

Notes 


This entry chases the link to its ultimate target. The ultimate target of 
a link must be a directory or segment, which may or may not exist. If the 
immediate target of alink is another link, the chasing of links continues 
toward the ultimate target directory or segment until it is encountered or found 
to be nonexistent. 
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If the ultimate target of the link exists, the user must either have status 
permission on the directory containing the target or nonnull access’ to the 
target itself in order to determine its pathname. If appropriate access exists, 
the code is zero, and link dir_name and link entryname are set. If not, an 
error code is returned, and the link dir name and link_entryname are returned as 
blank. 


If the ultimate target does not exist, the pathname of the last link 
encountered while chasing links will be returned if the user’ has status 
permission on the directoyr containing that final link. In this case, the 
returned code is error_table $noentry, and the link _dir_name and link_entryname 
are set. 


In all other cases, an error code is returned to indicate the lack of | 
access, and link _dir_name and link _entryname are returned as blanks. 
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Name: hes $get_max_ length 


The hes $get_max_length entry point, given a directory name and entryname, 
returns the maximum iength (in words) of the segment. 


Usage 


declare hes $get_max_length entry (char(*), char(*), fixed bin(19), 
fixed bin(35)); 


call hes $get_max_length (dir_name, entryname, max_length, code); 


where: 
ee dir_name (Input) 

is the pathname of the containing directory. 
2% entryname (Input) 

is the entryname of the segment. 
Ss max_length (Out put) 

is the maximum length of the segment in words. 
4, code (Output) 

is a storage system status code. 
Note 


The user must have status permission on the directory containing the 
segment or nonnull access to the segment. 
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Name: hes $get_max_length_seg 


The hes $get_max_length seg entry point, given a pointer to a segment, 
returns the maximum length (in words) of the segment. 


Usage 


declare hes $get_max_length_ seg entry (ptr, fixed bin(19), fixed bin(35)); 


call hes $get_max_length_seg (seg ptr, max length, code); 


where: 
Te seg_ptr (Input) 
is a pointer to the segment whose maximum length is to be returned. 
2. max length (Output) 
is the maximum length of the segment in words. 
3. code (Output) 
is a storage system status code. 
Note 


The user must have status permission on the directory containing the 
segment or nonnull access to the segment. 
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Name: hes $get_process usage 


The hes $get_process usage entry point returns information on system 
resource usage by the requesting process. 


Usage 


declare hes $get_process usage entry (ptr, fixed bin (35)); 


call hes $get_process_usage (process usage pointer, code); 


1. process usage pointer (Input) 
is a pointer to the structure described in "Notes" below. 


2. code (Output) 
is a standard status code. 


Notes 


The following structure, declared in process uSage.incl.pl1, is pointed to 
by process usage pointer: 


declare 1 process usage based (process usage pointer), 

2 number wanted fixed bin, 

2 number _can_ return fixed bin, 

2 cpu_time fixed bin (71), 
2 paging measure fixed bin (71), 
2 page faults fixed bin (34), 
2 pd faults fixed bin (34), 
2 virtual _cpu_time fixed bin (71), 
2 segment faults fixed bin (34), 
2 bounds faults fixed bin (34), 
2 vtoc reads fixed bin (34), 
2 vtoe writes fixed bin (34); 

where: 


1. number_wanted 
specifies now mucn information is to be returned in the structure. 
It must be set prior to the call to hes $get process usage, and its 
interpretation is given below. It is the only input parameter in 
the structure; all other items are output from 
hes $get_process usage or are ignored, depending on the value of 
number wanted. — 
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2. number can return 
~ is the number of system resource values which can be returned. It 
corresponds to the number of level 2 items in the structure 
following number _can_ return. This is returned for all values of 
number wanted. 


3. cpu_time 

is the cumulative central processor time for the process. It 
includes all time spent executing instructions outside of ring 0, 
all time spent executing instructions in ring 0 as’ the result of 
explicit calls to ring 0, and all overhead time while executing 
instructions in the address space of this process (e.g., processing 
page faults for this process and interrupts where this process was 
interrupted). This is returned if number_wanted is 1 or greater. 


4, paging measure 
is the cumulative memory usage for the process in billable memory 
units. This is returned if number_wanted is 2 or greater. 


Die page faults 
is the cumulative number of page faults by the process. This number 
represents the number of times a page was referenced which was not 
in main memory. This is returned if number_wanted is 3 or greater. 


6. pd faults 
~ is the cumulative number of paging device faults by the process. 
This number will be nonzero only if a paging device configured at 
the site. The number represents the number of page faults where the 
page faulted was not on the paging device. This is returned if 
number wanted is 4 or greater. 


Ts virtual _cpu_time 
is the cumulative virtual time for the process. This includes all 
time spent executing instructions outside of ring O and all time 
spent executing instructions in ring 0 as the result of explicit 
calls to ring 0. It does not include overhead time, such as the 
time spent processing page faults, segment faults, or interrupts. 
This is returned if number_wanted is 5 or greater. 


8. segment faults 
is the cumulative number of segment faults by the process. This 
represents the number of times a segment was referenced whose page 
table was not in main memory. This is returned if number wanted is 
6 or greater. 


9. bounds fauits 
is the cumulative number of bounds faults by the process. This 
represents the number of times an address within a segment was 
referenced that was beyond the segment bound. This occurs most 
commonly when a segment expands to the point where it requires a 
larger page table. This is returned if number_wanted is 7 or 
greater. 
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10. vtoc_reads 
is the number of read I/Os done by the process to Volume Table of 
Contents Entries (VTOCEs). This is returned if number wanted is 8 
or greater. = 


11. vtoc writes 
is the number of write I/Os done by the process to VIOCEs. This is 
returned if number wanted is 9 or greater. 


In the above description, cumulative activity by the requesting process is 
defined to mean all activity since login or since the most recent new_proc. 
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Name: hes $get_ring brackets 


The hes $get_ring brackets entry point, given the directory name _ and 
entryname of a segment, returns the value of that segment's ring brackets. 


Usage 


declare hes $get_ring brackets entry (char(*), char(*), (3) fixed bin(3), 
fixed. bin(35))3 


eall hes $get_ring brackets (dir_name, entryname, rb, code); 


where: 

Fs dir_name (Input) 
is the pathname of the containing directory. 

ae entryname (Input) 
is the entryname of the segment. 

3. rb (Out put) 
is a three-element array that contains the segment's ring brackets. 
Ring brackets and validation levels are discussed in "Intraprocess 
Access Control" in Section VI of the MPM Reference Guide. 

yy, code (Output) 
is a storage system status code. 

Note 


The user must have status permission on the containing directory. 
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Name: hes $get_safety sw 


The hes $get_ safety sw entry point, given a directory name and an 
entryname, returns the value of the safety switch of a directory or a segment. 


Usage 


declare hes $get_safety_ sw entry (char(*), char(*), bit(1), fixed bin(35)); 


call hes $get_safety sw entry (dir_name, entryname, safety sw, code); 


where: 
ae dir_name (Input) 

is the pathname of the containing directory. 
2. entryname (Input) 

is the entryname of the directory or segment. 
3% safety sw (Output) 

is the value of the safety switch. 

"O"b the segment or directory can be deleted 

ae as the segment or directory cannot be deleted 
4, code (Output) 

is a storage system status code. 
Note 


The user must have status permission on the containing directory or nonnull 
access to the directory or segment. 
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Name: hes $get_safety sw_seg 


The hes $get_safety sw_seg entry point, given a pointer to the segment, 
returns the value of the safety switch of a segment. 


Usage 


declare hes $get_safety_sw_seg entry (ptr, bit(1), fixed bin(35)); 


call hes $get_safety sw_seg (seg ptr, safety sw, code); 


where: 
Ts seg ptr (Input) 
is a pointer to the segment whose safety switch is to be examined. 
2. safety sw (Out put ) 
is the value of the segment safety switch. 
WOND the segment can be deleted 
se ls 3) the segment cannot be deleted 
cme code (Out put ) 
is a storage system status code. 
Note 


The user must have status permission on the directory containing the 
segment or must have nonnull access to the segment. 
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Name: hes $get_search_ rules 


The hes $get_search_rules entry point returns the search rules currently in 
use in the caller's process. 


Usage 


declare hes $get_search_rules entry (ptr); 


call hes $get_search_rules (search rules ptr); 


where search rules ptr (Input) is a pointer to a user-supplied search rules 
structure. See "Note" below. 


Note 


The structure pointed to by search rules ptr is declared as follows: 


del 1 search rules aligned, 
2 number fixed bin, 
2 names (21) char(168) aligned; 
where: 
1. number 


is the number of search rules in the array. 


es names 
are the names of the search rules. They can be absolute pathnames 
of directories or keywords. (See the hes $initiate search rules 
entry point for a detailed description of the search rules.) 
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Name: hes $get_system_search_ rules 


The hes $get_system_search_rules entry point provides the user with the 
values of the Ssite-defined search rule keywords accepted by 
hes $initiate search rules. 


Usage 


declare hes $get_system_search rules entry (ptr, fixed bin(35)); 


call hes $get_system_search_rules (search_rules ptr, code); 


where: 
We search rules ptr (Input) 
is a pointer to the structure described in "Notes" below. 
2. code (Out put) 
is a storage system status code. 
Notes 


The structure pointed to by search_rules ptr is declared as follows: 


del 1 drules based aligned, 
2 ntags fixed bin, 
2 nrules fixed bin, 
2 tags (10), 
3 name char(32), 
3 flag bit(36), 
2 rules (50), 
3 name char(168), 
3 flag bite36) 4 
where: 
ae ntags 


is the number of tags. 
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3% tags 
is an array of keywords. 


4, tags.name 
is the keyword. 


Bs tags.flag 
is a bit field with one bit on. 


6. rules 
is an array of directory names. 
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Vie rules.name 
is the absolute pathname of the directory. 


oe rules.flag 


is a bit field with bits on for every tag that selects this 
directory. 
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Name: hes $get uid seg 


The hes $get uid seg entry point, when given a pointer to a segment, 
returns the unique identifier associated with the segment. 


Usage 


declare hes $get uid seg entry (ptr, bit (36) aligned, fixed bin (35)); 


call hes $get_uid_ seg (seg ptr, unique id, code); 


where: 
1. seg ptr (Input) 
cones is a pointer to the segment whose unique identifier is to be 
determined. 
Pa unique id (Output) ; 
is the unique identifier associated with the segment. 
3. code (Output) 


is a standard storage system status code. 
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Name: hes $get_user_effmode 


The hes $get_user_effmode entry point returns the effective access mode of 
a user to a branch, given the pathname of the branch, the name of the user, and 
the validation level (ring number) of the user. (For a description of this 
mode, see "Effective Access" in Section 6 of the MPM Reference Guide.) 


Usage 


declare hes $get_user_effmode entry (char(*), char(*), char(*), fixed bin, 
fixed bin(5), fixed bin(35)); 


call hes $get_user_effmode (dir _name, entryname, user _id, ring, mode, 


code); 

where: 

1. dir_name (Input) 
is the directory name of the branch. 

2. entryname (Input ) 
is the entry name of the branch. 

3.  user_id (Input) 
is the access name of the user in the form 
Person id. Project_id_.tag. This is limited to 32 characters. If 
null, the access name of the calling process is used. 

4, ring (Input) 
is the validation level that is to be used in computing effective 
access. It must be a value between 0 and 7 inclusive, or -1. If 
the ring value is -1, a default value of the validation level of the 
calling process is used. This default should be used in all cases 
except those in which a different ring's access is explicitly 
required. 

Bie mode (Output) 
is the effective access mode of the user to the branch (see "Notes" 
below). 

6. code (Output ) 
is a standard status code. 

Notes 


The mode argument is a fixed binary number where the desired mode is 
encoded with one access mode specified by each bit. The modes for segments are: 


read the 8-bit is 1 (i.e., 01000b) 
execute the 4-bit is 1 (i.e., 00100b) 
write the 2-bit is 1 (i.e., 00010b) 
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hes $get_user effmode 


status the 8-bit is 1 (i.e., 01000b) 
modify the 2-bit is 1 (i.e., 00010b) 
append the ji-bit is 1 (i.e., O00001b) 
'The unused bits are reserved for unimplemented attributes and must be 0. For 


example, rw access is 01010b in binary 
access modes values.incl.pl1 include file defines mnemonics for these values: 


del (N ACCESS BIN init 
R ACCESS BIN init 
E ACCESS BIN Init 
W ACCESS BIN init 
RW ACCESS BIN init 
RE ACCESS BIN init 
REW ACCESS BIN init 
S ACCESS BIN init 
M ACCESS BIN init 
A ACCESS BIN init 
SA ACCESS BIN init 
SM ACCESS BIN init 


SMA ACCESS BIN init 
fixed bin (5) internal 


(00000b), 
(01000b), 
(00100b), 
(00010b), 
(01010b), 
(01100b), 
(01110b), 


(01000b), 
(00010b), 
(00001b), 
(01001b), 
(01010b), 
(01011b)) 


static options (constant); 


in decimal form. The 


The user must have status permission on the containing directory, unless 
the access name supplied is that of the calling process or null. 
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Name: hes $initiate_search_ rules 


The hes $initiate search rules entry point provides the user with a 
subroutine interface for specifying the search rules that he wants to use in his 
process. (For a description of the set search rules command, see the MPM 
Commands.) - 


Usage 
declare hes $initiate search rules entry (ptr, fixed bin(35)); 
call hes $initiate search rules (search_rules ptr, code); 
where: 
Ve search rules ptr (Input) 
is a pointer to a structure containing the new search rules. See 
"Notes" below. 
2s code (Output) 
is a storage system status code. 
Notes 


The structure pointed to by search rules ptr is declared as follows: 


del 1 search _ rules aligned, 
2 number fixed bin, 
2 names (21) char(168) aligned; 
where: 
Ts number 


is the number of search rules contained in the array. The current 
maximum number of search rules the user can define is 21. 


2. names 


are the names of the search rules. They can be absolute pathnames 
of directories or keywords. 


Two types of search rules are permitted: absolute pathnames of directories 
to be searched or keywords. The keywords are: 


1% initiated segments 
search for the already initiated segments. 


2. referencing dir 
search the containing directory of the segment making the reference. 


3. working dir 
search the working directory. 
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4, process dir 
search the process directory. 


on home_dir 
search the home directory. 


G5 set search directories 
~ insert the directories following this keyword into the default 
search rules after working dir, and make the result the current 
search rules. ~ 


Yi site-defined keywords 
may also be specified. These keywords may expand into one or more 
directory pathnames. The keyword, default, is always defined to be 
the site's default search rules. 


The set search directories keyword, when used, must be the first search 
rule specified and the only keyword used. If this keyword is’ used, 
hes $initiate search rules sets the default search rules, and then inserts’ the 
specified directories in the search rules after the working directory. 


Some of the keywords, such as _ set search directories, are expanded into 
more than one search rule. The limit of 21 search rules applies to the final 
number of search rules to be used by the process as well as’ to the number of 
rules contained in the array. 


The search rules remain in effect until this entry point is called with a 
different set of rules or the process is terminated. 

Codes that may be returned from this entry point are: 

error table $bad_ string (not a pathname or keyword) 

error table $notadir 

error table $too_ many sr 
Additional codes can be returned from other procedures that are called by 


hes $initiate_search_rules. 


For the values of the site-defined keywords, the user may call the 
hes $get_system_search rules entry point. 
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Name: hes $list_dir_inacl 


The hes $list dir inacl entry point is used either to list the entire 
initial access control list (initial ACL) for new directories created for the 
specified ring within the specified directory or to return the access modes for 
specified initial ACL entries. The dir acl ‘structure described in the 
hes _$add_dir_inacl_entries entry point is used by this entry point. 


Usage 
declare hes $list_dir_inacl entry (char(*), char(*), ptr, ptr, ptr, 
fixed bin, fixed bin(3), fixed bin(35)); 


call hes $list_dir_inacl (dir_name, entryname, area ptr, area _ret ptr, 
acl_ptr, acl_count, ring, code); 


where: 
ie dir_name (Input) 
is the pathname of the containing directory. 
2s entryname (Input) 
is the entryname of the directory. 
Be area _ ptr (Input) 
points to an area into which the list of initial ACL entries, which 
makes up the entire initial ACL of the directory, is allocated. If 
area ptr is null, then the user wants access modes for certain 
initial ACL entries; these Will be specified by the structure 
a L 3 tbh vu oepevriisacu vy vu 
pointed to by acl ptr (see below). 
H, area _ret_ptr (Out put ) 
points to the start of the allocated list of initial ACL entries. 
5. acl ptr (Input) 
if area _ptr is null, then acl ptr points to an initial ACL 
Structure, dir_acl, into which mode information is placed for the 
e access names specified in that same structure. 
6. acl_count (Input or Output) 
is the number of entries in the ACL structure. 
Input 
? is the number of entries in the initial ACL structure 
identified by acl ptr 
Out put 
is the number of entries in the dir_acl structure allocated 
in the area pointed to by area _ptr, if area ptr is not null 
ie ring (Input) 
is the ring number of the initial ACL. 
8. code (Output) 


is a storage system status code. 
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Note 


If acl ptr is used to obtain modes for specified access names (rather than 
obtaining modes for all access names on the initial ACL), then each initial ACL 
entry in the dir acl structure either has status code set to 0 and contains the 
directory's mode or has status code set to error table $user not found and 
contains a mode of 0. ~ ~ ~ = 
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Name: hes $list_inacl 


The hes $list inacl entry point is used either to list the entire initial 
access control list (initial ACL) for new segments created for the specified 
ring within the specified directory or to return the access modes for specified 
initial ACL entries. The segment acl structure used by this entry point is 
described in the hes $add_inacl entries entry point. 


Usage 
declare hes $list_inacl entry (char(*), char(*), ptr, ptr, ptr, fixed bin, 
fixed bin(3), fixed bin(35)); 


call hes $list_inacl (dir_name, entryname, area_ptr, area_ret_ptr, acl ptr, 
acl count, ring, code); 


where: 
Ls dir_name (Input) 
is the pathname of the containing directory. 
2% entryname (Input) 
is the entryname of the directory. 
3% area ptr (Input) 
points to an area into which the list of initial ACL entries, which 
makes up the entire initial ACL of the directory, is allocated. If 
area ptr is null, then the user wants access modes for certain 
initial ACL entries; these will be specified by the structure 
pointed to by acl_ptr (see below). 
yy, area_ret_ptr (Output) 
points to the start of the allocated list of initial ACL entries. 
Bo acl_ ptr (Input) 
if area_ptr is null, then acl ptr points to an initial ACL 
structure, segment_acl, into which mode information is to be placed 
for the access names specified in that same structure. 
6. acl_count (Input or Output) 
is the number of entries in the initial ACL structure. 
Input 
is the number of entries in the initial ACL structure 
identified by acl ptr 
Out put 
is the number of entries in the segment acl structure allocated 
in the area pointed to by area ptr, if area_ptr is not null 
Us ring (Input) 
is the ring number of the initial ACL. 
8. code (Out put ) 


is a storage system status code. 
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Note 


If acl ptr is used to obtain modes for specified access names (rather than 
obtaining modes for all access names on the initial ACL), then each initial ACL 
entry in the segment acl structure either has status code set to 0 and contains 
the segment's mode or has’ status code set to error table $user not found and 
contains a mode of 0. 7 a me rere as 
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Name: hes $quota_move 


The hes $quota_move entry point moves all or part of a quota between two 
directories, one of which is immediately inferior to the other. 


Usage 


declare hes $quota_move entry (char(*), char(*), fixed bin(18), 
fixed bin(35)); 


call hes $quota_move (dir_name, entryname, quota_change, code); 


where: 

Te dir_name (Input) 
is the pathname of the containing directory. 

ee entryname (Input) 
is the entryname of the directory. 

3% quota_change (Input) 
is the number of records of secondary storage quota to be moved 
between the superior directory and the inferior directory. (See 
"Notes" below.) 

4, code (Out put ) 
is a storage system status code. 

Notes 


The entryname specified by the entryname argument must be a directory. 
The user must have modify permission on both directories. 


After the quota change, the remaining quota in each directory must be 
greater than the number of records used in that directory. 


The quota change argument can be either a positive or negative number. If 
it is positive, the quota is moved from dir name to entryname. if 1&- 2s 
negative, the move is from entryname to dir name. If the change results in zero 
quota left on entryname, that directory is assumed to no longer contain a 
terminal quota and all of its used records are reflected up to the used records 
on dir name. It isa restriction that no quota in any of the directories 
superior to entryname can be modified from a nonzero value to a zero value by 
this subroutine. 
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Name: hes $quota_ read 


The hes $quota_ read entry point returns the segment record quota and 
accounting information for a directory. 


Usage 


declare hes $quota_read entry (char(*), fixed bin(18), fixed bin(71), 
bit(36) aligned, bit(36), fixed bin(1), fixed bin(18), fixed bin(35)); 


eall hes $quota_read (dir_name, quota, trp, tup, sons _ lvid, tace_ sw, used, 


code); 
where: 
qT dir_name (Input) 
is the pathname of the directory for which quota information is 
desired. 
Bs quota (Out put ) 
is the segment record quota in the directory. 
3. trp (Out put ) 
is the time-record product (trp) charged to the directory. This 
double-precision number is in units of record-seconds. 
4, tup (Out put ) 
is the time, expressed in storage system time format (the high-order 
36 bits of the 52-bit time returned by the clock _ subroutine, 
described in the MPM Subroutines), that the trp was last updated. 
Si sons lvid (Output) 
is the logical volume ID for segments contained in this directory. 
6. tacc sw (Output) 
is the terminal account switch. The setting of this switch 
determines how charges are made. 
1 records are charged against the quota in this directory 
0 records are charged against the quota in the first superior 
directory with a terminal account 
Te used (Output) 
is the number of records used by segments in this directory and by 
segments in nonterminal inferior directories. 
8. code (Output) 
is a storage system status code. 
Note 


If the directory contains a nonterminal account, the quota, trp, and tup 
are all zero. The variable specified by used, however, is kept up-to-date and 
represents the number of records in this directory and inferior, nonterminal 
directories. 
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Name: hes $replace dir _inacl 


The hes $replace dir inacl entry point replaces an entire initial access 
control list (initial ACL) for new directories created for the specified ring 
within a specified directory with a user-provided initial ACL, and _ can 
optionally add an entry for *.SysDaemon.* with mode sma to the new initial ACL. 
The dir_acl structure described in the hes $add dir _inacl_entries entry point is 
used by this entry point. ~ ~ 


Usage 
declare hes $replace dir _inacl entry (char(*), char(*), ptr, fixed bin, 
bit(1) aligned, fixed bin(3), fixed bin(35)); 
call hes $replace dir_inacl (dir_name, entryname, acl ptr, acl count, 
no_sysdaemon_ sw, ring, code); 
where: 


1. dir_name (Input) 
is the pathname of the containing directory. 


entryname (Input) 
is the entryname of the directory. 


N 


ce acl ptr (Input) 
points to a uSer-supplied dir acl structure that is to replace the 
current initial ACL. a 

4, acl count (Input) . 
contains the number of entries in the dir acl structure. 


Se no sysdaemon sw (Input) 
~ is a Switch that indicates whether the sma *.SysDaemon.* entry is 
put on the initial ACL after the existing initial ACL is deleted and 
before the user-supplied dir acl entries are added. 
"O"h adds sma *.SysDaemon.*® entry 
bs ua ©) replaces the existing initial ACL with only the user-supplied 
dir .ael 


ae ring (Input) 
is the ring number of the initial ACL. 


Ts code (Output) 
is a storage system status code. 


Note 


If acl count is zero, then the existing initial ACL is deleted and only the 


action indicated (if any) by the no_sysdaemon Sw switch is performed. If 
acl_count is greater than zero, processing of the dir_acl entries is performed 
top to bottom, allowing later entries to overwrite previous ones if the 


access name in the dir_acl structure is identical. 
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Name: hes $replace_inacl 


The hes $replace inacl entry point replaces an entire initial access 
control list (initial ACL) for new segments created for the specified ring 
within a specified directory with a user-provided initial ACL, and can 
optionally add an entry for *.SysDaemon.* with mode rw to the new initial ACL. 
The segment _acl structure described in the hes $add_inacl_entries entry point is 
used by this entry point. 


Usage 
declare hes $replace inacl entry (char(*), char(*), ptr, fixed bin, bit(1), 
fixed bin(3), fixed bin(35)); 


call hes $replace_inacl (dir_name, entryname, acl ptr, acl count, 
no _Sysdaemon_ sw, ring, code); 


where: 
1. dir_name (Input) 
is the pathname of the containing directory. 
2. entryname (Input) 
is the entryname of the directory. 
oe acl ptr Cinput) 
points to the user-supplied segment_acl structure that is to replace 
the current initial ACL. 
yu, acl count (Input) 
contains the number of entries in the segment_acl structure. 
Se no_sysdaemon_sw (Input) 
is a switch that indicates whether the rw *.SysDaemon.* entry is to 
be put on the initial ACL after the existing initial ACL is deleted 
and before the user-supplied segment _acl entries are added. 
WON adds rw *.SysDaemon.* entry 
bd 23 6, replaces the existing initial ACL with only the user-supplied 
segment acl 
6. ring (Input) 
is the ring number of the initial ACL. 
ie code (Output) 
is a storage system status code. 
Note 


If acl count is zero, then the existing initial ACL is deleted and only the 
action indicated (if any) by the no sysdaemon sw switch is. performed. If 
acl count is greater than zero, processing of the segment acl entries is 
performed top to bottom, allowing later entries to overwrite previous ones if 
the access name in the segment_acl structure is identical. 
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Name: hes $reset_ips mask 


The hes $reset_ips mask entry point replaces the entire ips mask with a 
specified mask, and returns the previous value of the mask with a control bit of 
"O"b. It can be used at the end of a critical section of code to restore the 
mask tO. its former value. See "Notes" in the description of the 
hes $get_ ips mask entry point for a discussion of the control bit. 


Usage 


declare hes $reset_ips_ mask entry (bit(36) aligned, bit(36) aligned); 


call hes $reset_ips_mask (mask, old mask); 


where: 
1. mask (Input) 
is the new ips mask, to replace the current one. A "1" bit in a 
mask position enables the corresponding ips interrupt. 
2. old mask (Output) 
is the former value of the ips mask, with a control bit of "O"b. 
Notes 


This entry point can be used at the end of a critical section of code to 
undo the mask changes made by the hes $set_ips_ mask entry point. The old _mask 
returned by the latter entry point should be used as the value of the new mask 
set by this entry point. 
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Name: hcs $set automatic ips mask 


The hes $set_ automatic ips mask entry point replaces the entire automatic 
ips mask with a supplied value, and returns the previous value of the automatic 
ips mask with a control bit of "1"b. 


Usage 


declare hes $set_automatic_ ips mask entry (bit(36) aligned, bit(36) 
aligned); 


call hes $set_automatic ips mask (mask, old_ mask); 


where: 

1. mask (Input) 
is the new value to replace the automatic ips mask. 

2. old mask (Output) 
is the former value of the automatic ips mask, with a control bit of 
NTMb, 

Notes 


The create ips mask _ subroutine (described in this manual) can be used to 
create a mask, given a set of ips names. 


The automatic ips mask controls the state of the ips mask at the time that 
an ips signal handler is called. The interpretation of the bits in the 
automatic ips mask is quite different from that of the bits in the ips mask. 
When an ips interrupt occurs, if the bit corresponding to that interrupt is on 
in the automatic ips mask, then automatic ips masking takes place -- i.e., all 
ips interrupts are temporarily masked off, as described below. If the bit is 
off, then the ips mask is not changed. 


If automatic ips masking is to take place for a given ips interrupt, then 
the current value of the ips mask is saved in the machine conditions, with its 
control bit on, and the ips mask is set to all zero bits, thus disabling all ips 
interrupts. This happens before the handler for the interrupt is called. When 
an ips interrupt handler returns, if the control bit in the saved-.ips mask is 
on, then the current ips mask is replaced by the saved one. It follows from 
this that the handler for an ips interrupt for which automatic ips masking is in 
effect can not make a permanent change to the ips mask unless it also modifies 
the machine conditions, turning off the control bit in the saved ips mask. 
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Name: hes _$set_dir_ring brackets 


The hes $set_dir_ring brackets entry point, given the pathname of the 
containing directory and the entryname of the subdirectory, sets the 
subdirectory's ring brackets. 


Usage 


declare hes $set_dir_ring brackets entry (char(*), char(*), 
(2) fixed bin(3), fixed bin(35)); 


call hes $set_dir_ring brackets (dir_name, entryname, drb, code); 


where: 

1. dir_name (Input) 
is the pathname of the containing directory. 

26 entryname (Input) 
is the entryname of the subdirectory. 

3. drb (Input) 
is a two-element array specifying the ring brackets of the 
directory. The first element contains the level required for modify 
and append permission; the second element contains the level 
required for status permission. 

i. code (Out put ) 
is a storage system status code. 

Notes 


The user must have modify permission on the containing directory. Also, 
the validation level must be less than or equal to both the present value of the 
first ring bracket and the new value of the first ring bracket that the user 
wishes set. 


Ring brackets and validation levels are discussed in "Intraprocess Access 
Control" in Section 6 the MPM Reference Guide. 
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Name: hes $set_entry bound 


The hes $set_entry bound entry point, given a directory name and = an 
entryname, sets the entry point bound of a segment. 


The entry point bound attribute provides a way of limiting which locations 
of a segment may be targets of a call. This entry point allows the caller to 
enable or disable a hardware check of calls to a given segment from other 
segments. If the mechanism is enabled, all calls to the segment must be made to 
an entry point whose offset is less than the entry point bound. 


In practice, this attribute is most effective when all of the entry points 
are located at the base of the segment. In this case, the entry point bound is 
the number of callable words. 


Usage 


declare hes $set_entry bound entry (char(*), char(*), fixed bin(14), 
fixed bin(35)); 


call hes $set_entry bound (dir_name, entryname, entry bound, code); 


where: 
La dir_name (Input) 
is the pathname of the containing directory. 
2. entryname (Input) 
is the entryname of the segment. 
oe entry bound (Input) 
is the new value in words for the entry point bound of the segment. 
If the value of entry bound is 0, then the mechanism is disabled. 
4, code (Output ) 
is a storage system status code. (See "Notes" below.) 
Notes 


A directory cannot have its entry point bound changed. 
The user must have modify permission on the containing directory. 


If an attempt is made to set the entry point bound of a segment greater 
than the system maximum of 16383, code is set to error table $argerr. 


The hes $set entry bound seg entry point can be used when a pointer to the 
segment is given, rather than a pathname. 
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Name: hes $set_entry bound seg 


The hes $set_entry bound seg entry point, given a pointer to a segment, 
sets the entry point bound of the segment. 


The entry point bound attribute provides a way of limiting which locations 
of a segment may be targets of a call. This entry point allows the caller to 
enable or disable a hardware check of calls to a given segment’ from other 
segments. If the mechanism is enabled, all calls to the segment must be made to 
an entry point whose offset is less than the entry point bound. 


In practice, this attribute is most effective when all of the entry points 
are located at the base of the segment. In this case, the entry point bound is 
the number of callable words. 


Usage 


declare hcs $set_entry bound seg entry (ptr, fixed bin(14), fixed bin(35)); 


call hes $set_entry_ bound seg (seg ptr, entry bound, code); 


where: 

1. seg ptr (Input) 
is a pointer to the segment whose entry point bound is to be 
changed. 

2x entry bound (Input) 
is the new value in words for the entry point bound of the segment. 
If the value of entry bound is 0, then the mechanism is disabled. 

3. code (Output) | 
is a storage system status code. (See "Notes" below.) 

Notes 


A directory cannot have its entry point bound changed. 
The user muSt nave modify permission on the containing directory. 


If an attempt is made to set the entry point bound of a segment to greater 
than the system maximum of 16383, code is set to error_table $argerr. 


The hes $set_entry bound entry point can be used when a pathname of the 
segment is given, rather than a pointer. 
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Name: hes $set_exponent_control 


This entry point changes the current settings of the flags that control the 
system's handling of exponent overflow and underflow conditions. For more 
information on exponent control see "Notes", 


Usage 
declare hes $set_exponent_control entry (bit(1) aligned, bit(1) aligned, 
float bin(63), fixed bin (35)); 


call hes $set_exponent_ control (restart underflow, restart overflow, 
overflow value, code); 


where: 

1. restart_underflow (Input) 
is "1"b if underflows should be automatically restarted, and "0"b 
otherwise. 

2. restart_overflow (Input) 
is "1"b if overflows should be automatically restarted, and "0"b 
otherwise. 

3. overflow _value (Input) 
is the value used for the result of the computation in the case of 
overflow. 

4, code (Output) 
is a standard status code. 

Notes 


When either of the two flags are set to zero, the corresponding error 
condition causes the appropriate fault condition to be signalled. If a flag is 
set to one, then the computation resulting in the error is automatically 
restarted. In the case of underflow its result is set to zero. In the case of 
positive overflow, its value is set to the value specified in overflow value. 
In the case of negative overflow, the negative of overflow value is used. The 
default value is the largest representable positive number, available as 
Default_exponent_control_overflow_value in the include £26 
exponent control.incl.pli. 


This subroutine affects only the system's handling of exponent overflow and 
underflow when the overflow condition or the underflow condition is raised. In 
certain cases, the error condition is raised instead; this subroutine does not 
affect the system's handling of such cases. 


In programs not’ written in PL/I, the exponent _control_ subroutine, 
described in MPM Subroutines, should be used in place of 
hes $set_exponent_control. 
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Name: hes $set_ips_ mask 


The hes $set ips mask entry point replaces the entire ips mask with a 
supplied value, and returns the previous value of the mask with a control bit of 
"ib. It can be used at the beginning of a critical section of code, to disable 
one or more ips interrupts, and turn on the control bit to indicate that some 
interrupts are disabled. See "Notes" in the description of the 
hes $get_ips_mask entry point for a discussion of the control bit. 


Usage 


declare hes $set_ips_ mask entry (bit(36) aligned, bit(36) aligned); 


call hes $set_ips_mask (mask, old_mask); 


where: 
see mask (Input) 
is the new value to replace the ips mask. A "1" bit in each mask 
position enables the corresponding ips interrupt. 
2. old mask (Output) 
is the former value of the ips mask, with a control bit of "1"b. 
Notes 


The create _ips_mask_ subroutine (described in this manual) can be used to 
create a mask, given a set of ips names. 


The hes $reset_ips_mask entry point (described in this manual) can be used 
at the end of a critical section of code to undo the mask changes made by this 
entry point, by setting the mask to the old_ mask value returned by this entry 
point. 
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Name: hes $set_max_length 


Tne hes $set_max_length entry point, given a directory name, sets the 
maximum length (in words) of a segment. 


Usage 


declare hes $set max length entry (char(*), char(*), fixed bin(19), 
fixed bin(35));_ 


call hes $set_max_length (dir_name, entryname, max_length, code); 


where: 
1. dir_name (Input) 
is the pathname of the containing directory. 
2. entryname (Input) 
is the entryname of the segment. 
3. max_length (Input) 
is the new value in words for the maximum length of the segment. 
4, code (Output) 
is a storage system status code. (See "Notes" below.) 
Notes 


A directory cannot have its maximum length changed. 
The user must have modify permission on the containing directory. 


The maximum iength of a segment is accurate to units of 1024 words, and if 
max length is not a multiple of 1024 words, it is set to the next multiple of 
1024 words. 


If an attempt is made to set the maximum length of a segment to greater 
than the system maximum, sys_info$max _5e8_ size, code is set to 
error table $argerr. The sys_info data base is described in Section VIII of 
this manual. 


If an attempt is made to set the maximum length of a segment to less than 
its current length, code is set to error table $invalid_max_length. 


The hes _$set_ max _length_seg entry point can be used when the pointer to the 
segment is given, rather than a pathname. 
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Name: hes _ $set_max_length_seg 


The hes $set_max_length_seg entry point, given the pointer to the segment, 
sets the maximum length (in words) of a segment. 


Usage 


declare hes $set_max_length_seg entry (ptr, fixed bin(19), fixed bin(35)); 


call hes $set_max_length_seg (seg ptr, max_length, code); 


where: 
Ts seg ptr (Input) 
is the pointer to the segment whose maximum length is to be changed. 
2% max length (Input) 
is the new value in words for the maximum length of the segment. 
3. code (Out put) 
is a storage system status code. (See "Notes" below.) 
Notes 


A directory cannot have its maximum length changed. 
The user must have modify permission on the containing directory. 


The maximum length of a segment is accurate to units of 1024 words, and if 
max length is not a multiple of 1024 words, it is set to the next multiple of 
1024 words. 


If an attempt is made to set the maximum length of a segment to greater 
than the system maximum, sys info$max seg size, code is set to 
error table $argerr. The sys_info data base is described in Section VIII of 
this manual. 


If an attempt is made to set the maximum length of a segment to less than 
its current length, code is set to error table $invalid_max_length. 


The hes_$set_max_length entry point can be used when a pathname of the 
segment is given, rather than the pointer. 
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Name: hes $set_ring_ brackets 


The hes $set ring brackets entry point, given the directory name and 
entryname of a nondirectory segment, sets the segment's ring brackets. 


Usage 


declare hes $set_ring brackets entry (char(*), char(*), (3) fixed bin(3), 
fixed bin(35))3 


call hes $set_ring brackets (dir_name, entryname, rb, code); 


where: 
ie dir_name (Input) 
is the pathname of the containing directory. 
ea entryname (Input) 
is the entryname of the segment. 
3. rb (Input) 
is a three-element array specifying the ring brackets of the 
segment; see "Notes" below. 
u, code (Output) 
is a storage system status code. 
Notes 


Ring brackets must be ordered as follows: 

rb1l <= rbe <= rb3 

The user must have modify permission on the containing directory. Also, 
the validation level must be less than or equal to both the present value of the 


first ring bracket and the new value of the first ring bracket that the user 
wishes set. 


Ring brackets and validation levels are discussed in "Intraprocess Access 
Control" in Section 6 of the MPM Reference Guide. 
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Name: hes $set_safety_ sw 


The hes $set safety sw entry point allows the safety switch associated with 
a segment or directory to be changed. The segment is designated by a directory 
name and an entryname. See "Segment, Directory, and Link Attributes" in Section 
2 of the MPM Reference Guide for a description of the safety switch. 


Usage 


declare hes $set_safety sw entry (char(*), char(*), bit(1), fixed bin(35)); 


call hes $set_safety_sw (dir_name, entryname, safety sw, code); 


where: 
Es dir_name (Input) 

is the pathname of the containing directory. 
2. entryname (Input) 

is the entryname of the segment or directory. 
ce safety_sw (Input) 

is the new value of the safety switch. 

OND if the segment can be deleted 

eb if the segment cannot be deleted 
4, code (Out put) 

is a etonraga auctam statiie anda 

hw a mvs +o. wywr yw ee ed wwYUYe 
Notes 


The user must have modify permission on the containing directory. 


The hes $set_safety sw_seg entry point can be used when the pointer to the 
segment is given, rather than a pathname. 
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Name: hes $set_safety sw_seg 


The hes $set_safety Ssw_seg entry point, given a pointer to a segment, sets 
the safety switch of the segment. See "Segment, Directory, and Link Attributes" 
in Section 2 of the MPM Reference Guide for a description of the safety switch. 


Usage 


declare hes $set_safety sw_seg entry (ptr, bit(1), fixed bin(35)); 


call hes_$set_safety sw_seg (seg ptr, safety sw, code); 


where: 
1. seg ptr (Input) 
is the pointer to the segment. 
2 safety sw (Input) 
is the new value of the safety switch. 
"O"b if the segment can be deleted 
"1"b if the segment cannot be deleted 
3. code (Out put) 
is a storage system status code. 
Notes 


The user must have modify permission on the containing directory. 


The hes $set_safety sw entry point can be used when a pathname of the 
segment is given, rather than the pointer. 
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Name: hes $star_ 


The hes $star_ entry point is the star convention handler for the storage 
system. (See "Constructing and Interpreting Names" in Section 3 of MPM 
Reference Guide.) It is called with a directory name and an entryname that is a 
star name (contains asterisks or question marks). The directory is searched for 
all entries that match the given entryname. Information about these entries is 
returned in a structure. If the entryname is **, information on all entries in 
the directory is returned. 


The main entry point returns the storage system type and all names that 
match the given entryname. (The hes $star_dir_list_ and hes_$star_list_ entry 
points: described below return more information about each entry. The 
hes $star_dir_list entry point returns only information kept in the directory 
branch, while the hes $star_list_ entry point returns information kept in the 
volume table of contents (Vf[O0C). Accessing the VTOC is an additional expense, 
and it can be quite time consuming to access the VTOC entries for all branches 
in a large directory. Further, if the volume is not mounted, it is impossible 
to access the VIOC. Therefore, use of the hes $star_dir_list_ entry point is 
recommended for all applications in which information from the VTOC is not 
essential. 


Status permission is required on the directory to be searched. 


Usage 


declare hes $star_ entry (char(*), char(*), fixed bin(2), ptr, fixed bin, 
ptr, ptr, fixed bin(35)); 


call hes $star_ (dir_name, star_name, star_select_sw, area_ptr, 
star_entry count, star_entry_ptr, star_names ptr, code); 


where: 
1.  dir_name (Input) 
is the pathname of the containing directory. 
2. star_name (Input) 
is the entryname that can contain asterisks or question marks. 
3. star_select_sw (Input) 


indicates what information is to be returned. It can be: 


star_LINKS ONLY (=1) 
information is returned about link entries only 


star_BRANCHES ONLY (=2) 
information is returned about segment and directory entries only 


star_ALL_ENTRIES (=3) 
information is returned about segment, directory, and link entries. 
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4, area_ptr (Input) 
is a pointer to the area in which information is to be returned. If 
the pointer is null, star_entry count is set to the total number of 
selected entries. See "Notes" below. 


5. .star_entry count (Output) 
is a count of the number of entries that match the entryname. 


6. star_entry_ptr (Output) 
is a pointer to the allocated structure in which information on each 
entry is returned. 


7.  star_names_ptr (Output) 
is a pointer to the allocated array of all the entrynames in this 
directory that match star_name. See "Notes" below. 


oss code (Output) 
is a storage system status code. See "Status Codes" below. 


Notes 


Even if area ptr is null, star entry count is set to the total number of 
entries in the directory that match star name. The setting of star _select sw 
determines whether star_entry count is the total number of link entries, the 
total number of segment and directory entries, or the total number of all 
entries. 


If area_ptr is not null, the entry information structure and the name array 
are allocated in the user-Supplied area. 


This data structure is declared in star_structures.incl.pl1. The entry 
information structure is as follows: 
declare 1 star_entries (star_entry count) aligned based (star_entry ptr), 
2 type fixed binary (2) unsigned unaligned, 
2 nnames fixed binary (16) unsigned unaligned, 
2 nindex fixed binary (18) unsigned unaligned; 
where: 
Ts type 


specifies the storage system type of entry (the following named 
constants are declared in star_structures.incl.pl1): 

star LINK (0) 

star SEGMENT (1) 

star DIRECTORY (2) 


Ze nnames 
specifies the number of names for this entry that match star_name. 


3. nindex 


specifies the offset in star_names of the first name returned for 
this entry. 
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All of the names that are returned for any one entry are. stored 
consecutively in an array of all the names allocated in the user-supplied area. 
The first name for any one entry begins at the nindex offset in the array. 


The names array, allocated in the user-supplied area and declared in 
star_structures.incl.pll, is as follows: 
declare star names (sum (star_entries (*).nnames)) char(32) 


based (star_names ptr); 


The user must provide an area large enough for the hes $star_ entry point 
to store the requested information. 


Status Codes 


If no match with star_name was found in the directory, code will be 
returned as error table $nomatch. 


If star _name contained illegal syntax with respect to the star convention, 
code will be returned as error table $badstar. 


If the user did not provide enough space in the area to return all 
requested information, code will be returned as error table $notalloc. In this 
ease, the total number of entries (for hes $star ) or the total number of 
branches” and the total number of links (for hes $star list and 
hes $star_dir_list_) will be returned, to provide an estimate of space required. 


Using the include file 


A program uSing star structures.incl.pl1 should declare addr, binary, and 


sum to be builtin. The arguments star_entry count, star_entry ptr, and 
Star_names ptr are declared in the include file along with named constants for 
the value of star select sw and the storage system type. One of the named 


constants for star select sw can be passed as an argument to hes $star_ along 
with star_entry count, star_entry ptr and star_names ptr. 


Entry: hes $star_list_ 


This entry point returns more information about the selected entries, such 
as the mode and records used for segments and directories and link pathnames for 
links. This entry point obtains the records used and the date of last 
modification and last use from the VTOC, and is, therefore, more expensive to 
use than the hes $star_dir_list_ entry point. 
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Usage 


declare hes $star_list_ entry (char(*), char(*), fixed bins) y-peErs 
fixed bin, fixed bin, ptr, ptr, fixed bin(35)); 


area_ptr, star_branch_ count, star_link_count, star _list_branch_ ptr, 


call hes $star_list_ (dir_name, star_name, star_select sw, 
star_list_names_ ptr, code); 


j where: 
a dir_name (Input) 
is the pathname of the containing directory. 
ae star_name (Input) 
is the entryname that can contain asterisks or question marks. 
3 star_select_sw (Input) 
indicates what information is to be returned. It can be: 
star_LINKS ONLY (=1) 
information is returned about link entries only 
Star_BRANCHES ONLY (=2) 
information is returned about segment and directory entries only 
Star_ALL_ ENTRIES (=3) 
information is returned about segment, directory, and link entries 
Star_LINKS ONLY WITH LINK PATHS (=5) 
information is returned about link entries only, including the 
pathname associated with each link entry 
Sstar_ALL_ENTRIES WITH LINK PATHS (=7) 
information is returned about segment, directory, and link entries, 
including the pathname associated with each link entry 
4, area ptr (Input) 
is a pointer to the area in which information is to be returned. If 
the pointer is null, star_branch_ count and star link count are set 
to the total number of selected entries. See "Notes" below. 
Bs star_branch_count (Output) 
is a count of the number of segments and directories that match the 
entryname. 
6. star_link_count (Out put) 
is a count of the number of links that match the entryname. 
ver star _list_branch_ptr (Output) 
is a pointer to the allocated structure in which information on each 
entry is returned. 
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Ox star_list_names_ ptr (Output) 
is a pointer to the allocated array in wnicn selected entrynames and 
pathnames associated with link entries are stored. 


9. code (Output) 
is a storage system status code. See "Status Codes" above in the 
description of hes $star_ entry point. 


Notes 


The names star LINKS ONLY through STAR _ALL_ ENTRIES WITH_LINK PATHS are 
declared in star_structures.incl.pl1. 


Even if area ptr is null, star branch count and star link count may be set. 
If information on segments and directories is requested, star branch count is 
set to the total number of segments and directories that match star name. If 
information on links is requested, star link count is the total number of links 
that match star_name. ~ = 


If area_ptr is not null, an array of entry information structures and the 
names array, aS described in the hes $star entry point above, are allocated in 
the user-supplied area. Each element in the structure array may be either of 
the structures described below (the star links structure for links or the 
star list branch structure for segments and directories). The correct structure 
is indicated by the type item, the first item in both structures. 


If the system is unable to access the VTOC entry for a branch, values of 
zero are returned for records used, date time contents modified, and 
date time used, and no error code is returned. Callers of this entry point 
should interpret zeros for all three of these values as an error indication, 


rather than as valid data. 


The first three items in each structure are identical to the ones in the 
structure returned by the hes $star_ entry point. 


The following structure, declared in star_structures.incl.pl1, is used if 
the entry is a segment or a directory: 


declare 1 star_list_branch (star branch count + star link count) 
aligned based (star list branch ptr), 
2 type fixed binary(2) unsigned unaligned, 
2 nnames fixed binary(16) unsigned unaligned, 
2 nindex fixed binary(18) unsigned unaligned, 
2 dtem bit(36) unaligned, 
2 dtu bit(36) unaligned, 
2 mode bit(5) unaligned, 
2 raw_mode bit(5) unaligned, 
2 master_dir : bit(1) unaligned, 
2 pad bit(7) unaligned, 
2 records fixed bin(18) unsigned unaligned; 
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10. 


ie 


where: 


type 


specifies the storage system type of entry: 
Star LINK (=0) 

link 
Star SEGMENT (=1) 


segment 


star DIRECTORY (=2) 
directory 


nnames 
specifies the number of names for this entry that match Star_name. 


nindex 
Specifies the offset in star _list_names of the first name returned 
for this entry. 


dtcm 
is the date and time the contents of the segment or directory were 
last modified. 
dtu 
is the date and time the segment or directory was last used. 
mode 
is the current user's access mode to the segment or directory. 
raw_mode 


is the current user's access mode before ring brackets and access 
isolation are considered. 


master dir 
specifies whether entry is a master directory: 


Wath yes 

NONbH no 
pad 

is unused space in the structure. 
records 


is the number of 1024-word records of secondary storage that have 
been assigned to the segment or directory. 


The following structure, declared in star_structures.incl.pl1, is used if 


| the entry is a link: 


declare 1 star links (star branch count + star link count) 
c aligned based (star list branch ptr), 
2 type fixed binary(2) unsigned unaligned, 
2 nnames fixed binary(16) unsigned unaligned, 
2 nindex fixed binary(18) unsigned unaligned, 
2 dtem bit(36) unaligned, 
2 dtd bit(36) unaligned, 
2 pathname len fixed binary(18) unsigned unaligned, 
2 pathname index fixed binary(18) unsigned unaligned; 


where: 
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Ts type . 
is the same as above. 


2. nnames 
is the same as above. 


3% nindex 
is the same as above. 


4, dtem 
is the date and time the link was last modified. 


Bs dtd 
is the date and time the link was last dumped. 


6. pathname_len 
is the number of significant characters in the pathname associated 
with the link. 


3 pathname index 
is the index in star_list_names of the link pathname. 


If the pathname associated with each link was requested, the pathname is 
placed in the names array and occupies six units of this array. The index of 
the first unit is specified by pathname index in the links array. The length of 
the pathname is given by pathname len in the links array. 


The following structure is the array of names. It is declared in 
Star _structures.inecl.pl1. 


declare star list names (sum (star links (*).nnames) + 
binary (star select sw >= star LINKS ONLY WITH LINK PATHS, 
1) * 6.* star_link_count) char (32) based (star list names ptr); 


The following based variable is used to get the pathname associated with 
link star _linkx in the star_links array. 1G. “Ls declared in 
star_structures.incl.pll. 


declare star_link pathname char (star_links (star_linkx).pathname_ len) 
based (addr (star list names (star links 
(star_linkx). pathname _index))); 


Using the Include File 


A program uSing star structures.inel.pl1 should declare addr, binary and 
sum to be builtin. The © star branch count, star entry ptr, star link count, 
star linkx, star list names ptr and star select sw Variables are declared in the 
include file along with named constants for the value of Star_select_sw and the 
storage system type. 


To use the structures in the include file, first assign to star_select_sw 
the proper named constant and then pass’ star select sw as an argument to 
hes $star_list along with star branch_ count, Star _link_count, 
star_ list_ branch _ptr, and star_list_names ptr. a 
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To get the link pathname associated with a link, assign to star _linkx the 
index of the link in star_links. Star_link pathname will then be link pathname. 


Entry: hes $star dir list_ 


This entry point returns information about the selected entries, such as 
the mode and bit count for branches, and link pathnames for links. It returns 
only information kept in directory branches, and does not access’ the VTOC 
entries for branches. This entry point is more efficient than the 
hes $star_list_ entry point. 


Usage 


declare hes $star dir list entry (char(*), char(*), fixed bin(3), ptr, 
fixed bin, fixed bin, ptr, ptr, fixed bin(35)); 


call hes $star_dir_list_ (dir name, star_name, star_select_sw, area ptr, 
star branch count, star link count, star_list_branch ptr, 
star list names _ptr, code); 


where the arguments are exactly the same as those for the hes $star_list_ entry 
point above. 


Notes 
The notes for hes $star_ list also apply to this entry. 


Use the following structure if the entry is a segment or a directory. The 
star_dir_ list_branch structure is the same as the star _list_branch structure 
except for the dtem and bit-count fields. This structure is declared in 
star _structures.incl.pl1. 


declare 1 star dir list branch (star_branch count + star link count) 
aligned based (star list branch ptr), 

2 type fixed binary(2) unsigned unaligned, 
2 nnames fixed binary (16) unsigned unaligned, 
2 nindex fixed binary (18) unsigned unaligned, 
2 dtem bit(36) unaligned, 
2 pad bit(36) unaligned, 
2 mode bit(5) unaligned, 
2 raw_mode bit(5) unaligned, 
2 master dir bit(1) unaligned, 
2 bit _count fixed binary(24) unaligned; 
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wnere: 
al type 
specifies the storage system type of entry: 
star LINK (=0) 
link 
star_SEGMENT (=1) 
segment 
star DIRECTORY (=2) 
directory 
2x nnames 
specifies the number of names for this entry that match star_name. 
me nindex 
specifies the offset in star_list_names of the first name returned 
for this entry. 
4, dtem 
is the date and time the directory entry for the segment or 
directory was last modified. 
oe pad 
is unused space in this structure. 
6. mode 
is the current user's access mode to the segment or directory. See 
the "Notes" section in the description of hes $get_user_effmode in 
this manual for a more detailed description of access modes. 
V3 raw_mode 
is the current user's access mode before ring brackets and access 
isolation are considered. 
8. master _dir 
specifies whether entry is a master directory: 
"qth yes 
"nOMb no 
Q. bit count 


is 


Tne star_links structure described 


a link. 


is the bit count of the segment or directory. 
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Name: hes $wakeup 


The hes $wakeup entry point sends an interprocess communication wakeup 
signal to a specified process over a specified event channel. If that process 
has previously called the ipe $block entry point, it is awakened. See the ipe 
subroutine description in this document. = 


Usage 


declare hes $wakeup entry (bit(36) aligned, fixed bin(71), 
fixed bin(71), fixed bin(35)); 


call hes $wakeup (process id, channel_id, message, code); 


where: 
1. process id (Input) 
is the process identifier of the target process. 
2.  channel_id (Input) 
is the identifier of the event channel over which the wakeup is to 
be sent. 
3. message (Input) 
is the event message to be interpreted by the target process. 
4, code (Output) 


is a standard status code. 
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Name: help_ 


The help subroutine performs the basic work of the help command (described 
in the MPM Commands). The help Subroutine is called to print selected 
information from one or more info segments. The caller may select: what 
information is to be printed; what search list is to be used to find the info 
segments; what suffix the info segments must have. Thus, the help- provides an 
interface for implementing a subsystem help command. = 


Several entry points in the help Subroutine are described below. 
help $init must be called before calling the help or help $check info segs 
entry points. The help or help $check info segs entry points may then be 
called one or more times. When the caller no longer needs the help args 
structure, help $term must be called to release the temporary segment containing 
the help args structure. 


Entry: help $init 


This entry point obtains a pointer to the help args structure (see "Notes" 
below). This structure is used to pass information from the caller to the help 
entry point (described below). The structure is a based structure containing 
several arrays with adjustable extents. The help $init entry point creates the 
structure in a temporary segment so that these arrays can be grown incrementally 
by the caller as information is added to the structure. 


The help Subroutine selects and prints info segments based upon the 


information given in the help args. structure. It also uses space in the 
temporary segment following the hel sc args Struevure ~ for @ werk erea.. For this 
reason, space for help args must be obtained by calling the help $init entry 


point. 


The help $init entry point obtains the paths defined in a search list named 
by the caller. It stores these paths in the help args structure for use by the 
help subroutine. Several other help args elements are set, as described under 
"Notes" below. a 


Usage 
declare help $init entry (char(*), char(*), char(*), fixed bin, ptr, 
fixed bin(35)); 
call help $init (caller, search _list_name, search _list_ref_dir, 
required_version, Phelp args, code); 
where: 
Ts caller (Input) 


is the name of the calling program, on whose behalf the temporary 
Segment containing the help args structure is obtained. 
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2. search list name (Input) 
is the name of the search list to be used in searching for info 
Segments. A null string may be given if no search list is to be 
used. 

3 search list ref dir (Input) 

“is the pathname of the directory to be used when expanding the 
referencing dir search rule in the search list. If a null string is 
given, the referencing dir search rule is omitted from the search 
TiS. = 

4, required version (Input) 


is the version number of the help args structure which the caller is 
prepared to accept. This argument should be set to the value of the 
Vhelp_args_1 constant, described under "Notes" below. 


ae Phelp_ args (Output) 
is a pointer to the help args structure, described under "Notes" 
below. 

6. code (Output) 


is a standard status code reporting any failure in obtain expanding 
the search list. 


Entry: help_ 


This entry point searches for info segments, selects information blocks 
(infos), and prints the information. The caller provides information in the 
help args structure (obtained in the call to help $init) to select the infos to 
be printed and the type of information to be printed. 


The help subroutine may ask the user questions about how much information 
should be printed. These questions and the responses the user may give are in 
the description of the help command in the MPM Commands. Questions are asked 
using the command query _ subroutine, described elsewhere in this manual. 


Usage 


declare help. entry (char(*), ptr, char(*), fixed bin; fixed bin(35)); 


call help (caller, Phelp args, suffix, progress, code); 


where: 

1. caller (Input) 
is as above. 

2% Phelp args (Input) 


is as above. 
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suffix (Input) 


is the suffix whicn must appear in the entrynames of info segments 
to be processed by this invocation of help . This suffix is also 
assumed when omitted from the (final or only) entryname of values 
given for help args.path.value in the help args structure (see 
"Notes" below). If anull string is given, then no suffix is 
required in info segment entrynames, and none is assumed in values 
of help args.path.value. 


progress (Output) 


is a special status code that indicates which stage of processing 
help was performing when an error occurs. The following values may 
be returned: 


the Phelp_ args argument points to an unimplemented version of the 
help _args structure. 


2 
help args.Npaths is not positive, indicating that no info names were 
given. help is unable to select info segments for printing, and 
reports the error. 

3 
an error is encountered while evaluating one or more of the 
help args.path.value values. help args.path.code indicates the 
particular error encountered in each Value. 

4 
no fatal errors are encountered. Some infos matching help args.path 
were found. Any nonfatal errors encountered while finding the infos 
are diagnosed to the user. A list of infos to be compared with the 
-section and ~search criteria is created. 

5 
infos matching the -section and -search criteria are printed. A 
nonzero code argument is returned only when no infos match the 
-section and -search criteria. help does not report such an error 
to the user. The caller is responsible for doing this. 

code (Out put) 

is a standard status code. When progress is 1, the code may have 


the following value: 


error table $unimplemented_ version 
help does not support the version of the help args’ structure 
pointed to by the Phelp args pointer argument. 


When progress is 2, the code may have the following value: 


error table $noarg 
help _args.Npaths was not positive. 


When progress is 3, the code may have any value returned by 
expand pathname $add_ suffix or check star_name gentry, or it may 
have the following value: 


error table $inconsistent 


a star name was given when help args.Sctl.ep = "1i"b, or when a value 
of help _args.path.value contains a subroutine entry point name. 
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When progress is 4, the code may have the following value: 


error table $nomatch 
No info segments match any of tne help args.path elements. For each 


help args.path.value element, help _ prints an error message when no 
matching info segments are found. 


When progress is 5, the code may have the following value: 


error table $nomatch 
None of the infos selected by help args.path contain sections whose 


titles match the selection criteria given in help _args.scn, or 
paragraphs that match the selection criteria given in help args.srh. 
help _ does not report this error to the user. The caller of help_ 


must do this. 
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Notes 


The Phelp args argument points to the following structure, which is 
declared in help args .incl.pl1: 


del 1 help args aligned based (Phelp args), 


2 version fixed bin, 
2. Seb l-, 
(3 he only, 
3 he pn, 
3 he info name, 
3 he counts, 
3 title, 
3 sen, 
3 Sr ny 
3 bf, 
5. Ca; 
3 ep, 
3 all) bite? una; 
3 padi bit(25) unal, 
2 Nsearch dirs fixed bin, 
2 Npaths. ' fixed bin, 
2 Neas fixed bin, 
2 Nsens fixed bin, 
2 Nsrhs fixed bin, 
2 min Lpgh fixed bin, 
2 max Lpgh fixed bin, 
2 Lspace between infos fixed bin, 
2 min date time _ fixed bin(71), 
2 pad2 (10) fixed bin, 
2 search_dirs (0 refer (help args.Nsearch dirs) ) 
char (168) unal, 
2 path (0 refer (help args.Npaths)), 
3 value ~ char(425) varying, 
3 info name char(32) unal, 
3 dir (1) echar(168) unal, 
3 ent ehar(32) unal, 
3 ep echar(32) varying, 
3 code fixed bin(35), 
3 


? 
(4 pn_ctl_arg, 
4 info name _not_starname, 
4 less greater, 
4 starname ent, 
4 starname info name, 
4 separate info name) bit(1) unal, 
4 pad3 bit(30) unal, 
2 ca (0 refer (help args.Neas)) 
char(32) varying, 
2 sen (0 refer (help args.Nsens)) 
char(80) varying, 
2 srh (0 refer (help _args.Nsrhs) ) 
char(80) varying, 
Phelp args ptr, 
Vhelp args 1 fixed bin int static 
options(constant) init(1); 
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where 
1. version 
is the version number of this structure (currently 1). The variable 
Vhelp args _1 (see 45 below) should be used when checking this 
version number. 
2s. Seul 


are flags controlling the operations which help_ performs on the 
info segments. help $init sets all of these flags to "O"b. 


3. Setl.he_ only 
help prints only a heading line identifying matching info segments. 
The heading line includes the info heading, plus heading fields 
selected by Sctl.he pn, Sctl.he info name and Sctl.he counts. No 


other information is printed. This flag is mutually exclusive with 
all other Sectl flags except those named above, Sctl.scn and 
SCtl.Sii. 


4H, Setl.he pn 
help includes the info pathname in all heading lines. help prints 
other information along with the heading line, as requested by the 
other Sctl flags. If no other flags are set, help_ prints the 
heading line followed by the first paragraph of information. 


5. Setl.he info name 

help includes the info name in all heading lines. This info name 
is included only when help args.path identifies an info segment 
containing more than one information block (info). (See 28 below 
for more information about info names.) help prints other 
information along with the heading line, as requested by other Sctl 
flags. If no other flags are set, help prints’ the heading line 
followed by the first paragraph of information. 


6. Setl.he counts 
“help includes info line counts and subroutine info entry point 
counts in all heading lines. help prints other information along 
with the heading line, as requested by other Sctl flags. If no 
other flags are set, help prints the heading line followed by the 
first paragraph of information. 


Tae “S@tlLstitLe 
help prints all section titles (including section line counts), 
then asks if the user wants to see the first paragraph. Normally, 
help_ just begins printing the first paragraph. 


8. Setl.sen 
help searches section titles for one containing all of the 
substrings given in help args.scn (see 42 below). If a matching 
title is found, help begins printing information requested by other 
Setl flags. If no other flags are set, help prints the first 
paragraph of the matching section. If no matching title is found, 
help_ skips the info without comment. 
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srh 

help searches all paragraphs for one containing all of the 
substrings given in help args.srh (see 43 below). If a matching 
paragraph is found, help begins printing information requested by 
other Sctl flags. If no other flags are set, help prints the 
matching paragraph. If no matching paragraph is found, help skips 
the info without comment. If Setl.sen is also "1"b, then only 
paragraphs from the matching section to the end of the info are 
searched. 


bf 


help prints only a brief summary of an info describing a command, 
active function, or subroutine. This flag is mutually exclusive 
with all other Sctl flags except Sctl.he pn, Setl.he info name, 
Setl.he counts, Setl.ca, Setl.sen and Scbl.srhs: ~ = 


Ca 


for an info describing a command, active function, or subroutine, 
help prints only the descriptions of one or more arguments or 
control arguments identified by the substrings in help args.ca (see 
41 below). This flag is mutually exclusive with all other Sctl 
flags except Scti.he pn, Setl.he info name, Sctl.he counts, Sctl.bf, 
Setl.sen and Setl.srh. = a 3 


.ep 


help. prints information describing the main entry point of a 
Subroutine, rather than information describing the general 
characteristics of all subroutine entry points. 


-all 


help prints all of the info without asking the user any questions. 


i8 reserve or future use. heip $init sets this fieid to ""b. 

ch dirs 
Is the number of directories help searches for info segments. The 
directory pathname are given in help args.search dirs (see 25 
below). This number is set by help $init to the number of paths in 
the search list named in the call to help $init, but the caller may 
change it before calling help . = 


is the number of info names help. searches for. The names are given 
in help _args.path (see 26 below). The caller must set this number 
before calling help . help $init initializes it to zero. 


is the number of substrings help uses in searching for argument or 
control argument descriptions when help args.Sctl.ca is given. The 
substrings are given in help args.ca (See 41 below). help $init 
initializes this number to zero. 


is the number of substrings help uses in searching for a matching 
section title when help args.Sctl.sen is given. The substrings are 
given in help args.scn (see 42 below). help $init initializes this 
number to zero. ~ 
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20. 
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22. 


es. 


24. 


254 


26. 


help_ 
Nsrhs 
is the number of substrings help uses in searching for a matching 
paragraph when help args.Sectl.srh is given. The substrings are 
given in help args.srh (see 43 below). help $init initializes this 
number to zero. ~ 
min _Lpgh 
is the length (in lines) of the shortest paragraph that help will 
consider as a distinct unit. Paragraphs shorter than this may be 
printed with their preceding paragraph, rather than asking the user 
if he wants to see the short paragraph. help $init initializes this 
number to 4, i 
max Lpgh 
7 is the maximum number of lines of information that help allows in 
grouper paragraphs before asking the user whether he wants to see 
more. help will never group’ short paragraphs with their preceding 
paragraph if the total number of lines to be printed (including 2 
blank lines between paragraphs) would exceed this number. 
help $init initializes this number to 15. 
Lspace between infos 
“is the number of blank lines which help prints between the last 
paragraph of one info and the heading line (or first paragraph) of 
the next. help $init initializes this number to 2. 
min_date_ time 


pad2 


is a Multics clock value. Only infos modified on or after the time 
gZiven in this clock value are selected. Info modification time is 
based upon the date time entry modified of the segment containing 
the info. When an info segment contains more than one info, any 
date given in the info heading is used as the modification date for 
that info. help $init initializes this number to -1, indicating 
that all infos are eligible for selection. 


is reserved for future use. This field should not be set or 
referenced. 


search dirs 


path 


is an array of absolute pathnames specifying directories that help 


will look in for named infos. help searches for an info unless 
help _args.path.value (see 27 below) contains less-than (<) or 
greater-than (>) characters, or unless 
help_args.path.S.pn_ctl_arg = "1"b (see 34 below). help $init sets 


this array to the pathnames given for the search list named by its 
search list_name argument. The caller can change this list before 
calling help_. Note that the search_dirs are absolute pathnames 
which are expanded from the rules in a search list. If the working 
directory may have changed between calls to help , then the search 
list rules must be reevaluated before each call to help . This can 
be accomplished by calling help $init before each call to help , and 
help $term after each call. = ~ 


is an array of minor structures that identify the infos’ to be 
printed. 
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28 « 


29s 


help. 


path.value 


is a value used to select one or more.info segments. A relative or 
absolute pathname may be given, or just an entryname. The (final or 
only) entryname may be a starname. A subroutine entry point name 
may follow the entryname. For example 


ioa_$rsnnl 
or 
my_info_dir>extend_subr$init 


A starname may not be given with a subroutine entry point name or 
when Sctl.ep = "1"b (see 12 above). A proper suffix (as defined by 
the suffix argument to the help entry point) is assumed if not 
given. If path.value contains a less-than (<) or greater-than (>) 
character, it is assumed to be the pathname of an info to be 
printed. Otherwise, path.value is assumed to be the entryname of an 
info which is searched for in directories named in the search dirs 
array (see 25 above). Note that path.value has a maximum length of 
425 characters to accommodate a maximum size pathname (168 
characters), a maximum size entry point name (256 characters), plus 
a dollar sign ($) separator. 


path.info name 


selects an info within the info segments found by path.value. 
Normally, the caller of help sets the info name to a null string, 
causing help to use the (final or only) .entryname from path.value 
(without its suffix) as the info name. help then searches for an 
info segment having the info name (with an appropriate suffix) as 
one of its segment names. help looks inside the segment to see if 
it is divided into different information blocks (infos). Lines of 
the form 


:Info: info_namel: ...info_ nameN: date info heading 


divide the segment into infos. For each info segment containing 
multiple infos, help searches for infos having an info_namei 
matching the info name and prints only those infos. 


When the caller of help gives a nonnull value for path.info name, 
then the info name need not be a name on the info segment itself. 
This is sometimes useful for subsystems which want to store all of 
their infos in a single info segment (to reduce’ storage costs, 
Simplify maintenance of the infos or facilitate printing all of the 
information), but which do not want to add all of the info names to 
the segment. This avoids the need for many names on the segment, 
and also prevents the system help command from accessing the infos 
whose names do not appear on the info segment. The star convention 
may be used in the path.info name. Note that the info namei given 
in a :Info: line of an info Segment correspond to names on the info 
segment when anull path.info name is given. However, when a 
nonnull path.info name is given, the info namei need not be unique 
within the info segment. help selects all infos having a matching 
info_namei in the order in which they appear in the info segment, 
even when path.info name is not a star name. If path.info name is 
set to a nonnull value, the pathS.info name not starname must also 
be set (see 35 below). = aoe 


path.dir 


is the directory part of a pathname given as the value of 
path.value. help sets this value, and the caller of help_ need not 
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set this value. The variable is a one-dimensional array so that it 
can be used interchangeably with the search dirs array (see 25 
above) in searching for info segments. 


30. path.ent 
is the entryname part of a pathname given as the value of 
path.value. help sets this value, and the caller of help need not 
set this value. — - 


31. path.ep 
is the entry point name part of a name given in path.value. help_ 
sets this value, and the caller of help_ need not set this value. 


32. path.code 

is a standard status code associated with processing the value given 
in path.value. When help returns to its caller with a progress 
argument value of 3 and a nonzero status code argument, the caller 
of help should: examine each path.code; for nonzero values, 
report an error in path.value. path.code may have any of the values 
listed above for the code argument returned by help when the 
progress argument is 3. = 


33. path.sS 
are flags controlling the interpretation of path.value (see 27 
above). 


34. path.S.pn ctl arg 
is "1" if path.value is to be interpreted as a relative or absolute 
pathname, rather than as an entryname which should be searched for 
using the search dirs (see 27 above). If the flag is "0O"b, then 
help interprets path.value as a pathname only if it contains a 
less-than (<) or greater-than (<) character. The caller of help 
must set this flag to the appropriate value. ~ 


35. path.S.info name not starname 
is "T"b if path.info name is not a star name, even though it may 
contain * or ? characters. A value of "O"b causes path.info name 
to be treated as a star name if it contains ¥* or ? characters. If 
the caller sets path.info name to a nonnull value (see 28 above), 
then this switch must be set. 


36. path.S.less_ greater 
is a flag that help uses to record that path.value contains 


less-than (<) or greater-than (>) characters, or that 
path.S.pn_ctl_arg was set. The caller of help need not set this 
flag. = 


37. path.S.starname ent 
is a flag that help uses to record the fact that the (final or 
only) entryname in path.value is a star name. The caller of help 
need not set this value. a 


38. path.S.starname_info_name 
is a flag that help uses to record that path.info_name is a star 
name. The caller of help need not set this flag. 


39. path.S.separate info name 
is a flag that help uses to record that path.info name was supplied 
by the caller of help , rather than being extracted from path.value 
by help_. The caller of help_ need not set this flag. 
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ne 


44, 


45, 


help_ 

path.S.pad3 
is a reserved field. The caller of help must set this field to 
zeros. 

ca 
is the array of substrings help uses in searching for argument or 
control argument descriptions when help args.Sctl.ca is given. If 
any of these strings appears in the argument name line of an 
argument or control argument description, then help prints’ the 
entire description. = 

sen 
is the array of substrings help uses in searching for a matching 
section title when help args.Sctl.sen is given. All of these 
substrings must appear (in any order) in a matching section title. 
Comparisons are made after all substrings are translated to 
lowercase, so the letter case of the substrings does not matter. 

srh 
is the array of substrings help uses in. searching for a matching 
paragraph when help args.Sectl.srh is given. All of the substrings 
must appear (in any order) in a matching paragraph. Comparisons are 
made after all substrings are translated to lowercase, so the letter 
case of substrings does not matter. 

Phelp args : 
is a pointer to the help args structure. help $init returns a value 
for this pointer argument. help , help $check info segs and 
help_$term require the pointer as an input argument. — a 

Vhelp args 1 


is a named constant which the caller of help $init should use for 
the required version argument. This constant can also be used to 
check the value of neip args.version. 


The structure above is somewhat complex, due to the many options provided 
by the help_ 
following steps to set structure elements: 


subroutine. Callers of help or help $check_info_segs can use the 


Set the Sctl flags to the required values. Set min Lpgh, max_Lpgh, 
Lspace_ between infos, and min_date_time values if you wish to change 
the defaults supplied by help $init. 


If any of the search dirs are to be set (or changed from the 
pathnames given in the Search list named in the call to help $init), 
then set Nsearch dirs to the correct value, and set the search dir 
array elements to the desired values. i 


Set Npaths to the number of info pathname/info name input values. 
Set the elements of help args.path for each of these input values. 
If the values are arguments in a subsystem help request, they can be 
placed in the help args.path structure as each argument is 
processed. In this case, add 1to Npaths as each argument is 
processed, then set help args.path(Npaths) to the appropriate input 
values. 


Provide substrings used in searching for argument or control 


argument descriptions, if any. Set Neas to the appropriate value, 
then store the substrings in the ca array. 
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Bes Provide substrings used in searching for section titles, if any. 
Set Nsens to the appropriate value, then store the substrings in the 
sen array. 


6. Provide substrings used in searching for matching paragrapns, if 
any. Set Nsrhs to the appropriate value, then store the substrings 
in the srh array. 


Note that when substrings for argument and ontrol argument matching, 
section title matching, or paragraph matching are not provided, Neas, Nsecns, or 
Nsrhs above need not be set. help $init initializes these values to Zero. 


Entry: help $check info segs 


This entry point searches for info segments modified since a given date. 
It returns a sorted list of info segments matching the selection criteria. The 
list is sorted by directory name, and within a directory by entryname. In 
addition, the help $check info segs entry point flags entrynames found in more 
than one directory. All but the first such duplicate segment are marked with a 
cross reference flag and are sorted after all unique info segments. The caller 
provides the selection criteria in the help args structure, obtained by calling 
help $init. In particular, help args.min date time specifies the info segment 
modification threshold (see 23 in the "Notes" above). 


Usage 
declare help $check_info_segs entry (char(*#), ptr, char(*), fixed bin, 
fixed bin(35), ptr); 


call help $check_ info_segs (caller, Phelp args, suffix, progress, code, 
PPDinfo_seg) ; 


where: 
ie caller (Input) 

is as described above for the help entry point. 
2. Phelps args (Input) 

is as described above for the help_ entry point. 
3% suffix (Input) 

is as described above for the help_ entry point. 
yu, progress (Output) 

is as described above for the help_ entry point. 
5x code (Output) 

is as described above for the help_ entry point. 
6.3 PPDinfo_seg (Output) 


points to the PDinfo_seg structure, described under "Notes" below. 
This structure contains a sorted list of pointers to descriptors for 
the selected info segments. 
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4 


The PPDinfo_seg argument points to the PDinfo_ seg structure that follows. 
This structure is declared in help cis args .inel.pl1. All structure values are 


set by help $check_info_segs. 


del 1 PDinfo_seg 
2 version 


aligned based(PPDinfo_seg), 
fixed bin, 


2N fixed bin(24), 
2 P (0 refer (PDinfo seg.N)) *s 
~ ptr unal, 
PPDinfo seg ptr, 
VPDinfo_seg_1 fixed bin int static 


options(constant) init(1); 


Each pointer PDinfo_seg.P points to the following info segment descriptor 
Structure, which is also declared in help cis args .incl.pll. 


del 1 Dinfo seg aligned based, 
2 Secross ref bit(36) aligned, 
2 dir ehar(168) unal, 
2 ent ehar(32) unal, 
2 info name ehar(32) unal, 
2ep char(32) var, 
2 uid bitt36}, 
2iI fixed bin(21), 
aan ie fixed bin, 
2 date fixed bin(71), 
(2 segment type bit(2), 
2 mode — bit(3), 
2 padi bit(31))-unal, 
2 code fixed bin(35); 

where: 


1. version 
is the version number of the PDinfo seg and Dinfo seg structures 
(currently 1). The variable VPDinfo Seg 1 (see 5 below) should be 
used when checking this version number. ~ 


is the number of info segments found. 


is the array of pointers to the Dinfo_seg structures which describe 
the info segments found by the selection criteria. 


4, PPDinfo_seg 
is a pointer to the PDinfo_seg structure. 


5. VPDinfo_seg_1 
is a named constant which the caller of help $check info segs should 
use when testing the value of PDinfo_seg.version. - 


6. Dinfo_seg 


is the structure which describes each info segment found by the 
selection criteria. 
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13. 
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15. 


16. 


17. 


18; 


19. 


help. 
cross ref 
is an info segment crossreference flag. If the flag equals "1"b, 
then several info segments were found having the same entryname but 
residing in different directories, and the info segment identified 
by this structure was not the first such duplicate. 
dir 
is the directory part of the pathname of the info segment. 
ent 
is the final entryname part of the pathname of the info segment. 
info_name 
is reserved for use by help _, and is always a null character string. 
ep 
is the subroutine entry point name given in the selection criteria 
for the info segment. 
uid 
is reserved for use by help _, and is always 0. 
I 
is reserved for use by help_, and is always 0. 
ie 
is the length (in characters) of the info segment. 
date 
is the date_time_ entry modified of the info segment. 
segment type 
1s the type of storage system entry identified by Dinfo_seg.dir and 
Dinfo_seg.ent. It may have one of the following values: 
"OQO"b link 
OCT IED segment 
mode 
is the user's access mode to the info segment. The three bits 
correspond to read, execute and write access mode. For example, rw 
access is expressed as "101"b. 
padi 
is reserved for future use. 
code 


is a standard status code encountered while processing this info 
segment. It may have any of the following values: 


error_table $noentry 
Dinfo_seg.dir and Dinfo_seg.ent identify a link whose target does 
not exist. 


error table $zero_length_ seg 
the info segment is empty. 


error table $bad syntax 
the info segment has a bit count which is not evenly divisible by 9. 
Therefore, the info segment does not contain a whole number of 
characters. 
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Entry: help $term 


This entry point releases the temporary segment in which the help args 
structure (and the PDinfo_seg and Dinfo_seg structures of help $check info _segs) 
are created. This entry point should be called before calling help_ $init again. 


Usage 


declare help $term entry (char(*), ptr, fixed bin(35)); 


call help $term (caller, Phelp_args, code); 


where the arguments are as described above for the help entry point. 
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Name: interpret resource desc 


The interpret resource dese_ subroutine provides a facility for displaying 
the contents of an KCP resource description, in a format similar to that used by 
the resource status command. 


USage 
declare interpret_resource desc _ entry (pointer, fixed bin, char (*), 
bit (36) aligned, bit (1) aligned, char (*) varying, fixed bin (35)); 


call interpret resource desc_ (resource desc ptr, nth, callername, 
string (rst_control), return_noprint, return_string, code); 


where: 

1. resource desc ptr (Input) 
is a pointer to the structure containing the RCP resource 
description to be displayed. (See the resource control 
subroutine. ) 

2. nth (Input) 
specifies which element of the resource description is to be 
displayed (the index to the array resource descriptions.item). If 
nth is zero, all elements will be displayed. 

3 eallername (Input) 
is the name of the command invoking interpret resource desc_. It is 
used in printing any necessary error messages. 

4, rst control (Input) 
is declared in the include file rst_control.incl.pli. (See "Display 
Control" below.) 

5. return noprint (Input) 
specifies, if "O"b, that information about the resource description 
is to be written to the user_output I/0 switch. If "i"b, the 
information is returned in return string, nth must not be zero, and 
the elements of the structure rst _control must be set so that 
exactly one item of information is requested. 

6. return_string (Output) 
contains, if return_noprint is "1"b, a printable representation of 
the information requested. Otherwise, its contents are undefined. 

ie code - (Output) 


is a standard status code. 
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Display Control 


The rst_control structure § (declared in the inelude file 
rst_control.inel.pl1) is defined as follows: 


del 1 rst control aligned, 
2 default bit (1) unaligned, 
2 name bit (1) unaligned, 
2 uid bit (1) unaligned, 
2.potential attributes bit (1) unaligned, 
2 attributes bit (1) unaligned, 
2 desired attributes bit (1) unaligned, 
2 potential aim range bit (1) unaligned, 
2 aim range bit (1) unaligned, 
2 owner bit (1) unaligned, 
2 acs path bit (1) unaligned, 
2 location bit (1) unaligned, 
2 comment bit (1) unaligned, 
2 charge type bit (1) unaligned, 
2 mode ~— bit (1) unaligned, 
2 usage lock bit (1) unaligned, 
2 release lock bit (1) unaligned, 
2 awaiting clear bit (1) unaligned, 
2 user alloc bit (1) unaligned, 
2 given flags bit (1) unaligned, 
2mbz ~ bit (16) unaligned, 
2 any_given_ item bit (1) unaligned; 
where: 
1. default 

if "1i"b, signifies that certain items of information are to be 

displayed only if they are not in the most common state. This bit 

hould not be used by non-system commands. 

2. name 
is "i"b if item.name is to be displayed. 
3. uid 


is "1"b if item.uid is to be displayed. 


4. potential attributes 
is "1"b if item.potential_ attributes is to be displayed. 


5. attributes 
is "i"b if item.attributes is to be displayed. 


6. desired attributes 
Is "1"b if item.desired attributes is to be displayed. 


7- potential aim range 
is "1"b if item.potential_ aim_range is to be displayed. 


8. aim range 
~ is "1"b if item.aim_range is to be displayed. 


9. owner 
is "i"b if item.owner is to be displayed. 
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10. 


11. 


12. 


13. 


14. 


15. 


16. 


Tih. 


18. 


19. 


20. 


21. 


4/80 


acs path 
pam is "1"b 
location 
is "7b 
comment 
is myth 
charge type 
“is "1th 
mode 
is Wath 
usage lock 
~ is "Ib 
release lock 
Is wtb 
awaiting clear 
is "1b 
user alioc 
= is "1"b 


given flags 


if 


‘af 


if 


if. 


if 


if 


if 


if 


if 


item.acs path is to be displayed. 

item. location is to be displayed. 
item.comment is to be displayed. 
item.charge type is to be displayed. 
item.mode is to be displayed. 
item.usage lock is to be displayed. 
item.release lock is to be displayed. 
item.awaiting clear is to be displayed. 


item.user_alloc is to be displayed. 


interpret resource desc 


is "1"b if the state of all.the flags in the structure item.given is 
to be displayed. 


mbz 


any given item 
~ is "1"b 


t 


o display any field in the item structure for 


corresponding bit in the item.given structure is "1"b. 
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Name: iod_info_ 


The iod_ info _ subroutine extracts information from the I/0 daemon tables 
needed by those commands and subroutines that submit I/0 daemon requests. 


Entry: iod_info $generic_ type 


This entry point returns the generic type of a specified request type as 
defined in the I/0 daemon tables. For example, the generic type for the 
"unlined" request type might be "printer". Refer to the print request types 
command in the MPM Commands for information on generic types available for 
specific request types. 


Usage 


declare iod_info $generic_ type entry (char(*), char(32), fixed bin(35)); 


call iod_info_$generic type (request_type, generic type, code); 


where: 
Ts request type (Input) 
Is the name of a request type as defined in the I/O daemon tables. 
2. generic type (Out put) 
Is the name of the generic type of the above request type. 
3% code (Out put ) 


is a standard status code. If the specified request type is not . 
found, the code error table $id_not_found is returned. 


Entry: iod_info_$driver_access_name 


This entry point returns the driver access name for a_ specified request 
type as defined in the I/0 daemon tables. For example, the driver access name 
for the "printer" request type might be "I0.SysDaemon.*®". 
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Usage 


declare iod_ info $driver_access name entry (char(*), char(32), 
fixed bin(35)); 


call iod_info $driver_access name (request _type, access name, code); 


where: 
1. request_type (Input ) 
is the name of a request type as defined in the 1/0 daemon tables. 
ae access_name (Out put) 
is the driver access name for the above request type. 
34 code (Out put ) 


is a standard status code. If the specified request type is not 
found, the code error_table $id_ not found is returned. 


Entry: iod_info_ $queue data 


This entry point examines the I/O daemon tables and returns the default 
queue and maximum number of queues for a given request type. 


Usage 


declare iod info $queue_ data entry (char(*), fixed bin, fixed bin, fixed 


bin(35); 
call iod_info_$queue data entry (request_type, default _q, max queues, 
_eode); 

where 
q request type (Input) 

is the name of the request type as defined in the I/O daemon tables 
2s default_q (Output) 

is the number of the default queue for the request type. 
3 max queues (Output) 

is the number of queues for the request type. 
4, code (Output) 


is a standard status code. If the specified request type is not 
found, the code error table $id_ not found is returned. 


Entry: iod_info_ $rqt_list 


This entry point examines the I/0 daemon tables and returns a list of 
request types of a given generic type. 
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Usage 


declare iod info $rqt_list entry (char(32), (*) char(32), fixed bin, fixed 
bin(35)); 


call iod_info_$rqt_list entry (gen_type, q_list, n_queues, code); 


where: 

Ts gen_type (Input) 
is the generic type of request types to be listed. If the string is 
blank, then all request types are listed. 

2. q_list (Output) 
is an array that is filled in with the request type names to be 
returned. If the h-bound of this array is less than the number of 
names to be returned, the code error table $too_many names will be 
returned, with the partial list. 

ce n_queues (Output) 
is the number of entries returned in the q_list array. 

y, code (Out put ) 


is a standard status code. If there are no matching entries, the 
code error table $no_entry is returned. 
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Name: iox $init_standard_iocbs 


The iox_$init_standard_iocbs entry point attaches the standard switches for 
a user process. These are currently user_input, user _output, and error output, 
and they are attached with an attach description of: 

syn_ user_i/o 


The variables iox_$user_input, iox_$user_output, and iox_$error_output are set 
to the iocb pointers for these switches. 


Usage 


declare iox_$init_standard_iocbs entry (); 
call iox $init standard iocbs; 
Notes 


Should the standard attachments change, this program will change to 
establish whatever they are. It should therefore be used in any direct process 
overseer that wishes to establish standard attachments. 


7/81 7-140. 1 AK92C 


THIS PAGE INTENTIONALLY LEFT BLANK 


7/81 | AK92C 


ipe_ ipe 


Name: ipc_ 


The Multics system supports an interprocess communication facility. The 
basic purpose of the facility is to provide control communication (by means of 
stop and go signals) between processes. ; 


The ipe_ subroutine is the user's interface to the Multies interprocess 
communication facility. Briefly, that facility works as follows: a process 
establishes event channels in the current protection ring and waits for an event 
on one or more channels. 


Event channels can be thought of as numbered slots in the interprocess 
communication facility tables. Each channel is either an event-wait or 
event-call channel. An event-wait channel receives events that are merely 
marked as having occurred and awakens the process if it is blocked waiting for 
an event on that channel. On an event-call channel, the occurrence of an event 
causes a specified procedure to be called if (or when) the process is blocked 
waiting for an event on any channel. Naturally, the specific event channel must 
be made known to the process that expected to notice the event. For an event to 
be noticed by an explicitly cooperating process, the event channel identifier 
value is typically placed in a Known location of a shared segment. For an event 
to be noticed by a system module, a _ subroutine call is typically made to the 
appropriate system module. A process can go blocked waiting for an event to 
occur or can explicitly check to see if it has occurred. If an event occurs 
before the target process goes blocked, then it is immediately awakened when it 
does go blocked. 


The user can operate on an event channel only if his ring of execution is 
the same as his ring when the event channel was created (for a discussion of 
rings see "Intraprocess Access Control" in Section VI of the MPM Reference 
Guide). 


The hes $wakeup entry point (described in this document) is used to wake up 
a blocked process for a specified event. 
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Entry: ipe_$create_ev_chn 


This entry point creates an event-wait channel in the current ring. 
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Usage 
declare ipe $create_ev_chn entry (fixed bin(71), fixed bin(35)); 


call ipe $create _ev_chn (channel_id, code); 


where: 
1. channel _ id (Output ) 
is the identifier of the event channel. 
2% code (Output) 
] is a standard status code. 


Entry: ipe_$delete_ev_chn 


This entry point destroys an event channel previously created by the 
process. 
Usage 

declare ipec_$delete ev_chn entry (fixed bin(71), fixed bin(35)); 


call ipe_$delete ev_chn (channel_id, code); 


where: 
1. channel id (Input) 

is the same as described above for ipe $create_ev_chn. 
2. code (Output) 


is the same as described above for ipe_$create_ev_chn. 


| Entry: ipe $decl_event_call_chn 
This entry point changes an event-wait channel into an event-call channel. 


Usage 


declare ipe_ $decl_event_call_chn entry (fixed bin(71), entry, ptr, 
fixed bin, fixed bin(35)); 


call ipe_$decl_event_call_chn (channel_id, call_chn_procedure, data_ptr, 
priority, code); 
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where 


1. 


eae 


Entry 


ipe_ 


channel id (Input) 
is the identifier of the event channel. 
call _chn_ procedure (Input) 


is the procedure entry point invoked when an event occurs on the 
specified channel. 


data_ptr (Input) 
is a pointer to a region where data to be passed to and interpreted 
by that procedure entry point is placed. 


priority (Input) 
is a number indicating the priority of this event-call channel as 
compared to other event-call channels declared by this process for 
this ring. If, upon interrogating all the appropriate event-call 
channels, more than one is found to have received an event, the 
lowest-numbered priority is honored first, and so on. 


code (Output) 
is a standard status code. 


: ipe $decl_ev_wait_chn 


This entry point changes an event-call channel into an event-wait channel. 


Usage 


where 


1. 


2. 


declare ipe_$decl_ev_wait_chn entry (fixed bin(71), fixed bin(35)); 
call ipe $decl_ev_wait_chn (channel_id, code); 


channel _ id (Input) 
is the same as described above for ipe $create _ev_chn. 


code (Output) 
is the same as described above for ipe $create ev_chn. 


Entry: ipc $drain_chn 


event 
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This entry point resets an event channel so that any pending events (i.e., 
Ss that have been received but not processed for that channel) are removed. 
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Usage 


déclare ipe $drain_chn entry (fixed bin(71), fixed bin(35)); 


call ipe_ $drain_chn (channel _id, code); 


where: 
ce channel id (Input) 

is the same as described above for ipe_$create_ev_chn. 
2. code (Output) 


is the same as described above for ipe $create_ev_chn. 


Entry: ipe_$cutoff 


This entry point inhibits the reading of events on a specified event 
channel. Any pending events are not affected. More can be received, but do 
not cause the process to wake up. 


Usage 


declare ipe $cutoff entry (fixed bin(71), fixed bin(35)); 


call ipe $cutoff (channel_id, code); 


where: 
Vs channel _ id (Input) 

is the same as described above for ipe_$create_ev_chn. 
2. code (Out put) 


is the same as described above for ipe $create_ev_chn. 
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Entry: ipe $reconnect 


This entry point enables the reading of events on a specified event channel 
for which reading had previously been inhibited (using the ipe $cutoff entry 
point). All pending signals, whether received before or during the time reading 
was inhibited, are henceforth available for reading. 


Usage 


declare ipe $reconnect entry (fixed bin(71), fixed bin(35)); 


Call ipe $reconnect (channel_id, code); 
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where: 
1. channel_id (Input) 

is the same as described above for ipe $create ev_chn. 
oe code (Output) 


is the same as described above for ipe $create _ev_chn. 


Entry: ipe $set_wait_prior 


This entry point causes event-wait channels to be given priority over 
event-call channels when several channels are being interrogated; e.g., when a 
process returns from being blocked and is waiting on any of a list of channels. 
Only event channels in the current ring are affected. 

Usage 


declare ipe $set_wait_prior entry (fixed bin(35)); 


call ipe $set_wait_prior (code); 


where code (Output) is a standard status code. 


Entry: ipe $set_call_ prior 


This entry point causes event-call channels to be given priority over 
event-wait channels when several channels are being interrogated; e.g., upon 
return from being blocked and waiting on any of a list of channels. Only event 
channels in the current ring are affected. By default, event-call channels have 
priority. 

Usage 
declare ipe $set_call_prior entry (fixed bin(35)); 


call ipe_ $set_call_ prior (code); 


where code (Output) is a standard status code. 
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Entry: ipe_ $mask_ev_calls 


This entry point causes the ipe $block entry point (see below) to 
completely ignore event-calls occurring in the user's ring at the time of this 
call. This call causes a mask counter to be incremented. Event calls are 
masked if this counter is greater than zero. 

Usage 


declare ipc_ $mask_ev_calls entry (fixed bin(35)); 


call ipe_$mask_ev_calls (code); 


where code (Output) is a standard status code. 


Entry: ipe_ $unmask ev_calls 


This entry point causes the event-call mask counter to be decremented. 
Event calls remain masked as long as the counter is greater than zero. To force 
event calls to become unmasked, call this entry point repeatedly, until a 
nonzero code is returned. 


Usage 
declare ipe $unmask_ev_ calls entry (fixed bin(35)); 


call ipe $unmask ev_calls (code); 
where code (Output) is a standard status code. A nonzero code is returned if 
event calls were not masked at the time of the call. 
Entry: ipe $block 


This entry point blocks the user's process until one or more of a specified 
list of events has occurred. 
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Usage 


ipc_ 


.. declare ipe $block entry (ptr, ptr, fixed bin(35)); 


call ipe $block (event _wait_list_ ptr, event _wait_info_ptr, code); 


where: 


1. event_wait_list_ptr (Input) 


is a pointer to a structure that specifies the channels on which 
events are being awaited. This Structure is declared in 
event wait list.incl.pll. 


del 1 event_wait_list based aligned (event _wait_list_ptr), 
2 n_channels fixed bin, 


2 channel id (event_wait list _n channels refer 
(event wait list.n_channels)) fixed bin(71); 


where: 


n_channels 
is the number of channels. This item must be allocated 
on an even-word boundary. 


pad 
must be zero. 


channel id 
is an array of channel identifiers selecting the 
channels to wait. on. 
Frequently ipe $block is called with only one channel in the wait 
list. In this case, the following structure may be used. It is 
declared in event wait channel.incl.pll. 


del 1 event wait channel aligned, 


2 n_channels fixed bin initial (1), 
2 pad bit(36), 
2 channei_id (i) fixed bin(71); 


2. event wait info ptr (Input) 
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is a pointer to a structure into which the ipe $block entry point 
can put information about the event that caused it to return (i.e., 
that awakened the process). This structure is declared in 
event _wait_info.incl.pli. 


del 1 event _wait_info based aligned (event_wait_info_ ptr), 
2 channel id fixed bin(71), 
2 message fixed bin(71), 
2 sender bit(35), 
2 origin, 
3 dev_signal bit(18) unaligned, 
3 ring fixed bin(17) unaligned, 
2 channel index fixed bin; 
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where: 


channel _ id 
is the identification of the event channel. 


message 
is an event message as specified to the 
entry point. 


sender 


ipe_ 


hes $wakeup 


is the process identifier of the sending process. 


dev_signal 


indicates whether this event occurred as’ the result of 


an I/O interrupt. 
"4 Ith yes 
"O"b no 


ring 
is the sender's validation level. 


channel _ index 


is the index of channel _id in the event wait list 


structure above. 


Ss code (Output) 
is a standard status code. 
Entry: ipe_$read_ev_chn 


This entry point reads the information about an event on 
channel if the event has occurred. 


Usage 


declare ipe $read _ev_chn entry (fixed bin(71), fixed bin, ptr, 
fixed bin(35)); 


call ipe $read_ev_chn (channel_id, ev_occurred, info ptr, code); 


a specified 


where: 
il channel id (Input) 
Is the identifier of the event channel. 
26 ev occurred (Output) 
~ indicates whether an event occurred on the specified channel. 
0 no event occurred 
1 an event occurred 
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3. info ptr (Input) 
is as above. 


4, code (Output) 
is a standard status code. 


Invoking an Event-Call Procedure 


When a process is awakened on an event-call channel, control is immediately 
passed to the procedure specified by the ipe $decl event _call_ channel entry 
point. The procedure is called with one argument, a pointer to the following 
structure. This structure is declared in event _call_info.incl.pll. 


del 1 event_call_info based aligned (event _call_info ptr), 
2 channel_id fixed bin(71), =" 
2 message fixed bin(71), 
2 sender bitcs6)., 
2 origin, 
3 dev_signal bit(18) unaligned, 
3 ring fixed bin(17) unaligned, 
2 data _ptr ptr; 
where: 


1. channel _ id 
is the identifier of the event channel. 


ea message 
is an event message as specified to the hes $wakeup entry point. 


3% sender 
is the process identifier of the sending process. 


4. dev_signal 
indicates whether the event occurred as the result of an I/0 


interrupt. 
LL LD 9) yes 
NOMb no 


5s ring 
is the sender's validation level. 


6. data ptr 
points to further data to be used by the called procedure. 
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Notes 


A user should be familiar with interprocess communication in Multics and 
the pitfalls of writing programs that can run asynchronously within a process. 
For example, if a program does run asynchronously within a process and it does 
input or output with the tty _ 1/0 module, then the program should issue the 
start control order of tty before it returns. This is necessary because a 
wakeup from tty_ may be intercepted by the asynchronous program. 


If a program establishes an event-call channel, and the procedure 
associated with the event-call channel uses static storage, then the event-call 
procedure should have the perprocess static attribute. This is not necessary if 
the procedure is part of a limited subsystem in which run units cannot be used. 
See the description of the run command in MPM Commands for more information on 


run units and perprocess static. 
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Name: match star_name_ 


The match star_name_ subroutine implements the Multics storage system star 
convention by comparing an entryname with a name containing stars or question 
marks (called a star name). Refer to "Constructing and Interpreting Names* in 
Section 3 of the MPM Reference Guide for a description of the star convention 
and a definition of acceptable star name formats. 


Usage 


declare match _star_name_ entry (char(*), char(*), fixed bin(35)); 


call match_star_name_ (entryname, star_name, code);" 


where: 


ls entryname (Input) 


is the entryname to be compared with the star name. Trailing spaces 
in the entryname are ignored. 


2. star_name (Input) 
is the star name with which entryname is compared. Trailing spaces 
in the star name are ignored. 


3. code (Output) 
is a standard status code. It can be: 
error table $nomatch 
the entryname does not match the star name 
error table $badstar 
the star name does not have an acceptable format 


Notes 


Refer to the description of the hes $star_ entry point in this document to 
see how to list the directory entries that match a given star name. 


\ 


Refer to the description of the check star name subroutine in this 
document to see how to validate a star name. 
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Name: mde 


The mdec_ subroutine (actually a ring 1 gate) provides a_ series of entry 
points for manipulation of master directories. , 


Entry: mde $create dir 


This entry point is used to create a new master directory. Its arguments 
are roughly analogous to the hes $append_branchx entry point. 


Usage 


declare md¢ $create dir entry Cchar(*), char(*), char(*):, 
(3) fixed bin(3), char(*), fixed bin, fixed bin(35)); 


? 


fixed bin(5), 


call mde_$create dir (dir_name entryname, volume, mode, rings, user id, 
quota, code); 


where: 

2 dir_name (Input) 
is the pathname of the containing directory. 

ee entryname (Input) 
is the entryname of the subdirectory. 

3. volume (Input) Se 
is the name of the logical volume that is to contain segments 
ereated in the new directory. 

My mode (Input) 
is the user's access mode. 

53 rings (Input) 
are the ring brackets of the directory. 

6. user_id (Input) 
is an access control name. 

ie quota (Input) 
is the quota to be placed on the new directory. 

&. code (Output ) 


is a standard status code. 
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Entry: mde $create_ dirx 


This entry point is an extension of the mde $create dir entry point, which 
is similiar to hes $create_branch_ entry point. = 
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Usage 
declare mde $create dirx entry (char(*), char(*), char(*), ptr, 
fixed bin(35)); 


call mde_$create dirx (dir_name, entryname, volume, info ptr, code); 


where: 


1.  dir_name 
is as above. 


2. entryname 
is as above. 


3. volume 
is as above. 


4, info_ptr (Input) 
is a pointer to a Status structure as described under 
hes $create_branch_ entry point. 


Entry: mde $delete dir 


This entry point is used to delete a master directory. 


Usage 


declare mdc $delete dir entry (char(*), char(*), fixed bin(35)); 


call mde $delete dir (dir_name, entryname, code); 


where: 


1. dir name 
is as above. 


2. entryname 
is as above. 


3% code 
is as above. 


Entry: mde _$set_mdir_ quota 


This entry point is used to set the quota on a master directory. 
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Usage 
declare mdc $set_mdir_ quota entry (char(*), char(*), bit{1) aligned, 
fixed bin, fixed bin(35)); 


call mde $set_mdir_quota (dir_name, entryname, sw, quota, code); 


where: 


1.  dir_name 
is as above. 


2. entryname 
is as above. 


3. Sw (Input) 
is a switch indicating the kind of quota change. 
FOND sets the directory quota to the quota parameter. 


eT"D algebraically adds the quota parameter to the current 
directory quota. 


4, quota 
is as above. 


Be code (Output) 
is a standard system status code. : 
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Entry: mdc_$set_volume quota 


This entry point is used to set the volume quota for a quota account on a 
logical volume. 


Usage 
declare mde $set_volume quota entry (char(*), char(*), bit(1) aligned, 
fixed bin, fixed bin(35)); 


call mde_$set_volume quota (volume, account, sw, quota, code); 


where: 


1s volume 
is as above. 


2. account (Input) 
is the name of the quota account in the form 
Person id.Project_id.tag. The quota account name may contain stars. 


is as above. 
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2. account (Input) 
is the name of the quota account in the form 
Person _id.Project_id.tag. The quota account name may contain stars. 


3. SW 
is as above. 
4, quota 
is as above. 
Os code (Output) 


is a standard system status code. 


Entry: mdc $set_mdir_owner 


This entry point is used to set the owner name of a master directory. 


Usage 


declare mde _$set_mdir_owner entry (char(*), char(*), char(*), 
fixed bin(35)); 


call mde_$set_mdir_owner (dir_name, entryname, owner, code); 


where: 
ity dir_name 
is as above. 
2% entryname 
is as above. 
3. owner (Input) 
is the new owner name of the master directory, in the form 
person _id.project_id.tag. 
4, code (Output) 


is a standard system status code. 
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Entry: mde $set_mdir_ account 


This entry point is used to set the quota account of a master directory. 


Usage 
declare mdc_$set_mdir_account entry (char(*), char(*), char(*), 
fixed bin(35)); 


call mdce_$set_mdir_ account (dir_name, entryname, account, code); 


where: 


1. dir_name 
is as above. 


2 entryname 
is as above. 


3s account 
is the name of the new quota account. The directory quota is 
returned to the old account and redrawn from this new account. 


4, code . 
is as above. 
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Entry: mhes $get_seg usage 


This entry point returns the number of page faults taken on a segment since 
its creation. 


Usage 


declare mhcs $get_ seg usage entry (char(*), char(*), fixed bin(35), 
fixed bin(35)); 


call mhes_ $get_seg_ usage (dir_name, entryname, use, code); 


where: 
Ve dir_name (Input) 
is the directory containing the segment. 
2. entryname (Input) 
is the entryname of the segment. 
35 use (Out put) 
is the page fault count. 
4, code (Output) 
is a standard status code. 
Notes 


This entry point works for segments only and cannot be used to determine 
the page faults on a directory. 
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Entry: mhes $get_seg_ usage ptr 


This entry point works the same as mhcs $get_seg usage except that it takes 
a pointer to the segment. 
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Usage 


- declare mhes $get_ seg usage ptr entry (ptr, fixed bin(35), fixed bin(35)); 


call mhes $get_seg_ usage ptr (s ptr, use, code); 


where: 
1. s_ptr | (Input) . 
is a pointer to the segment. 
Zs use (Out put ) 
is as above. 
Se code (Out put) 


is as above. 
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‘Name: msf manager _ 


The msf manager subroutine provides a centralized and consistent facility 
for handling multisegment files. Multisegment files are files that can require 
more than one segment for storage. Examples of multisegment files are listings, 
data used through I/0 switches, and APL workspaces. The msf manager’ subroutine 
makes multisegment files almost as easy to use aS Single ségment files in many 
applications. 


A multisegment file is composed of one or more components, each the size of 
a segment, identified by consecutive unsigned integers. Any word in a single 
segment file can be specified by a pathname and a word offset. Any word in a 
multisegment file can be specified by a pathname, component number, and word 
offset within the component. The msf manager subroutine provides the means for 
creating, accessing, and deleting components, truncating the multisegment file, 
and controlling access. 


In this implementation, a multisegment file with only component 0 is stored 
as a single segment file. If components other than 0 are present, they are 
stored as segments with names corresponding to the ASCII representation of their 
component numbers in a directory with the pathname of the multisegment file. 


To keep information between calls, the msf manager Subroutine stores 
information about files in per-process data structures called file control blocks. 
The user is returned a pointer to a file control block by the entry point 
msf manager $open. This pointer, feb ptr, is the caller's means of identifying 
the multisegment file to the other msf manager entry points. The file control 

' 


hi be i a th <2 hAni 
block is freed by the msf manager $close- entry point. 


Entry: msf manager _$open 


manager $open entry point creates a file control block and returns 


The msf 
a pointer to it. The file need not exist for a file control block to be created 
for 1b. 
Usage 
declare msf_manager_$open entry (char(*), char(*), ptr, fixed bin(35)); 
call msf manager_$open (dir_name, entryname, feb ptr, code); 
where: 
ts dir name (Input) 
is the pathname of the containing directory. 
2. entryname (Input) 


is the entryname of the multisegment file. 
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ce feb ptr (Output) 
~ is a pointer to the file control block. 


4, code (Output) 


is a storage system status code. The code error table $dirseg is 
returned when an attempt is made to open a directory. > 


Note 


If the file does not exist, feb ptr is nonnull and the codeerror table ¢noentry 
is returned. If the file cannot be opened, feb ptr is null and the value of 
code returned indicates the reason for failure. ~— 
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Entry: msf manager Sget ptr 


The msf manager $get ptr entry point returns a pointer toa specified component 
in the multisegment file. The component can be created if it does not exist. 
If the file is a single segment file, and a component greater than 0 is requested, 
the single segment is converted to a multisegment file. This change does not 
affect a previously returned pointer to component 0. 


Usage 


declare msf manager $get ptr entry (ptr, fixed bin, bit(1), ptr, fixed 
bin(24), fixed bin(35)); 


call msf manager $get ptr (feb ptr, component, create sw, seg ptr, be, 


code); 
where: 
de feb ptr (Input) 
is a pointer to the file control block. 
2% component (Input) 
is the number of the component desired. 
ce create sw (Input) 
is the create switch. 
ne Baa 8) create the component if it does not exist 
nO" do not create the component if it does not exist 
4, seg ptr (Output) 


is a pointer to the specified component in the file, or null (if 
there is an error). 
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5. be (Output) 
is the bit count of the component. 


6. code . (Output) 
is a storage system status code. It may be one of the following: 
error table $namedup 
If the specified segment already exists or the specified reference 
name has already been initiated ; 
error table $segknown 
If the specified segment is already known 


Entry: msf manager $msf_ get ptr 


The msf manager $msf get ptr entry point returns a pointer to a specified 
component in the multisegment file. The component can be created if it does not 
exist. If the file is a single segment file, and the requested component is not 
component 0, the single segment is converted to a multisegment file. This change 
does not affect a previously returned pointer to component 0. If the file does 
not exist, it is created as a "mulit-segment file" with a single component. 
This entry point never creates a single segment file. (See also the 
msf manager $get ptr entrypoint.) 


Usage 
declare msf manager ¢msf get ptr entry (ptr 
bin(24), fixed ~binZ(35)): 


call msf_manager_$msf_get_ptr (fcb ptr, component, create sw, seg ptr, 
be. code); 


where: 
1. feb ptr (Input) 
is a pointer to the file control block. 
2% component (Input) 
is the number of the component desired. 
3. create sw (Input) 
is the create switch. 
"i%b create the component if it does not exist 
"O"b do not create the component if it does not exist 
y, seg ptr (Output) 
is a pointer to the specified component in the file, or null (if 
there is an error). 
5. be (Output) 


is the bit count of the component. 
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6. code (Output) 
is a storage system status code. It may be one of the following: 
error table snamedup 
if the specified segment already exists or the specified reference 
name has already been initiated 
error table ¢segknown 
if the specified segment is already known 


Entry: msf_manager_ $adjust 


The msf_manager_$adjust entry point optionally sets the bit count, truncates, 
and terminates the components of a multisegment file. The number of the last 
component and its bit count must be given.- The bit counts of all components 
with numbers less than the given component are set to sys infot$max seg size*36. 
All components with numbers greater than the given component are deleted. All 
components that have been initiated are terminated. A 2-bit switch is used to 
control these actions. 


Usage 


declare msf manager Sadjust entry (ptr, fixed bin, fixed bin(24), bit(3), 
fixed Bin(35)); 


call msf_ manager $adjust (feb ptr, component, bc, switch, code); 
where: 


Ts feb ptr (Input) 
~ is a pointer to the file control block. 


2 component (Input) 
is the number of the last component. 


3. be (Input) 
is the bit count to be placed on the last component. 


yy, switch (Input) 
is a ?-bit count/truncate/terminate switch. 


bit count 

"O"b do not set the bit count 

erp set the bit count 

truncate 

"O"b do not truncate the given component 

"1b truncate the given component to the length specified in the 
be argument 

terminate 

"OND do not terminate the component 

wT" 5 terminate the component 


5. code (Output) 
is a storage system status code. 
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Entry: msf_manager_$close 


This entry point terminates all . components that the file control block 
indicates are initiated and frees the file control block. 


Usage 


declare msf_manager_$close entry (ptr); 


call msf_manager_$close (feb_ptr); 


where fcb_ ptr is the pointer to the file control block. 


Entry: msf manager _$acl_ list 


This entry point returns the access control list (ACL) of a multisegment 
file. 


Usage 
declare msf_manager_ $acl_ list entry (ptr, ptr, ptr, ptr, fixed bin, 
fixed Bin(35)); 


call msf_manager_$acl_list (feb. ptr’; area_ptr, area_ret_ptr, acl ptr, 
acl_count, code); = 


where: 

Tes feb_ptr (Input) 
is a pointer to the file control block. 

2 area ptr (Input) 
points to an area in which the list of ACL entries, which make up 
the entire ACL of the multisegment file, is allocated. If area ptr 
is null, then the user wants access modes for certain ACL entries; 
these will be specified by the structure pointed to by acl ptr (see 
below). 

3. area ret ptr (Out put) - 
points to the start of the allocated list of ACL entries. 

4, acl_ptr (Input) : 
if area_ptr is null, then acl_ptr points to an ACL structure, 
segment acl, (described in "Notes" below) into which mode 


information is placed for the access names specified in that same 
structure. 
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5. acl count (Input/Output) 
is the number of entries in the segment_acl structure. 
Input 


ee 


msf manager 


is the number of entries in the ACL structure identified by 


acl_ ptr 
Output 


is the number of entries in the segment acl 


structure 


allocated in the area pointed to by area ptr, if area ptr is 


not null 


6. code (Out put ) 
is a storage system status code. 


Notes 


The following is the segment acl structure: 


del 1 segment_acl (acl_count) aligned based (acl ptr), 
2 access name char(32), 
2 modes bit(36), 
2 zero_pad bit(36), 
2 status_code fixed bin(35); 
where: 
Ve access name 


“is the access name (in the form Person id.Project_id.tag) that 


identifies the process to which this ACL entry applies. 


2. modes 


contains the modes for this access name. The first 


correspond to the modes read, execute, and write. 


three bits 


The remaining 


bits must be 0's. For example, rw access is expressed as "101"b. 


a% zero_pad 


must contain the value zero. (This field is for use with extended 


access and may only be used by the system.) 


4, status_code 


is a storage system status code for this ACL entry only. 


If acl ptr is used to obtain modes for specified access names 
obtaining modes for all access names in area_ret_ptr), then each 
the segment acl structure either has status code set to 0 and 
multisegment mode of the file or ~ has status code 
error_table $user_not_found and contains a mode of 0. ~ 


Entry: msf_manager_$acl_replace 


This entry point replaces the ACL of a multisegment file. 


7-162 


(rather than 
ACL entry in 
contains the 

set to 


AK92 


msf manager_ msf manager _ 


Usage 


declare msf_manager_$acl_ replace entry (ptr, ptr, fixed bin, bit(1), 
fixed bin(35))3 


call msf_manager_$acl_replace (feb _ptr, acl_ptr, acl_count, no_sysdaemon_sw 


code); 

where: 

1. feb_ptr (Input) 
is a pointer to the file control block. 

2: acl ptr (Input) 
points to the user-supplied segment_acl structure (described in the 
msf manager_$acl_list entry point above) that is to replace the 
current ACL. 

3. acl count (Input) 
is the number of entries in the segment acl structure. 

4, no_sysdaemon_sw (Input) 
is a Switch that indicates whether an rw *.SysDaemon.* entry is to 
be put on the ACL of the multisegment file after the existing ACL 
has been deleted and before the user-supplied segment_acl entries 
are added. 
"OND adds rw *.SysDaemon.* entry 
a Naa 6. replaces the existing ACL with only the user-supplied 

segment acl 

5. code (Out put) 
is a Storage System status code. 

Notes 


If acl_count is zero, the existing ACL is deleted and only the action 
indicated (if any) by the no _Sysdaemon_sw switch is performed. If acl_count is 
greater than zero, processing of the segment acl entries is performed top to 
bottom, allowing a later entry to overwrite a previous one if the access name in 
the segment acl structure is identical. 


Entry: msf_manager_$acl_ add 


This entry point adds the specified access modes to the ACL of the 
multisegment file. 
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Usage 


declare msf_manager_$acl_add entry (ptr, ptr, fixed bin, fixed bin(35)); 


call msf_manager_$acl_add (feb ptr, acl_ptr, acl count, code); 


where: 
1:3 feb_ptr (Input) 
is a pointer to the file control block. 
2. acl_ ptr (Input) 
points to the user-supplied segment_acl structure (described in the 
msf_manager_$acl_list entry point above). 
3. acl_count (Input) 
is the number of ACL entries in the segment acl structure. 
4, code (Output) 
is a storage system status code. 
Note 


If code is returned as error table $argerr, then the erroneous ACL entries 
in the segment acl structure have status_code set to an appropriate error code. 
No processing is performed. 


Entry: msf_manager_$acl_ delete 


This entry point deletes ACL entries from the ACL of a multisegment file. 


Usage 


declare msf_manager_$acl_delete entry (ptr, ptr, fixed bin, fixed bin(35)); 


call msf_manager_$acl_ delete (feb ptr, acl_ ptr, acl_count, code); 


where: 
1. feb_ptr (Input) 
is a pointer to the file control block. 
2 acl ptr (Input) 
points to a user-Supplied delete _acl structure. See "Notes" below. 
3. acl count (Input) 
is the number of ACL entries in the delete acl structure. 
4, code (Output) 


is a storage system status code. 
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Notes 


The delete acl structure is as follows: 


del 1 delete_acl (acl_count) / aligned based (acl ptr), 
2 access name. | char(32), 
2 status _code fixed bin(35); 
where: 


Ts access name 
“is the access name (in the form Person_id.Project_id.tag) of an ACL 
entry to be deleted. 


rae status_code 
“is a storage system status code for this ACL entry only. 


If code is error_table $argerr, no processing is performed and status code 
in each erroneous ACL entry is set to an appropriate error code. 


If an access name matches no name already on the ACL, then the status code 
for that delete acl entry is set to error table $user not_ found. Processing 
continues to the end of the delete acl structure and code is returned as 0. 
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Name: nd_handler_ 


This subroutine attempts to resolve the name duplication caused when a 
program tries to create a segment, muitisegment file, or link in a directory 
that already contains an entry by the same name. If the existing entry has 
additional names, nd handler tries to delete the name needed for the new entry 
and, if successful, prints a warning message. If the existing entry has only 
one name, nd handler queries the user whether or not.to delete it. A zero 
status code in either case means that nd handler _ has succeeded, and the calling 
program can retry creating the new entry. 


Entry: nd _handler_ 


Usage 


del nd handler_ entry (char(*), char(*), char(*), fixed bin(35)); 
call nd_handler_ (caller, dn, en, code); 


where: 
Tt caller (Input) 
is the name of the calling program, used in printed messages. 
2. dn (Input) 
is the pathname of the directory involved. 
ce en (Input) 
is the name of the entry that the calling program wants to create. 
uy code (Output) 
is a standard status code. It may be: 
0 
if the old entryname has been removed 
error table $action _not_performed 
If the user answered "no" to a query 
other codes 
if the old entryname could not be removed for some other reason 
such as’ lack of access. An error message is then printed by 
nd_handler . 
Notes 


This subroutine is usually called after another subroutine call has 
returned error table $namedup. If nd handler returns a zero status code, the 
other subroutine is called a second time. A warning message of the following 
kind is printed if the existing entry has multiple names: 


caller: Name duplication. Old name foo removed 
from >udd>m>Smith>oldseg. 
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If the existing entry has only one name, wording of the query depends on 
the existing entry's type: 


caller: Do you want to delete the old segment <path>? 
caller: Do you want to delete the old multisegment file <path>? 
caller: Do you want to unlink the old link <path>? 
(Target <path2> exists.) 
or: (Target <path2> does not exist.) 


or: (Cannot get info for target <path2>.) 
or: (No target pathname.) 


The following entry points have the same calling sequence. 


Entry: ‘nd handler $force 


This entry point deletes the existing entry if it has only one name, rather 
than issue a query. 


Entry: nd handler $del 


This entry point queries whether or not to delete the existing entry, 
regardless of whether or not it has additional names. 


Entry: nd_handler $del_ force 


This entry point deletes the old entry (no query), regardless of whether it 
has additional names. 
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Name: object _info_ 


The object_info_ subroutine returns structural and identifying information 
extracted from an object segment. It has three entry points returning 
progressively larger amounts of information. All three entry points have 
identical calling sequences, the only distinction being the amount of 
information returned in the structure described in "Information Structure" 
below. 


Entry: object_info_ $brief 


This entry point returns only the structural information necessary to 
locate the object's major sections. 


Usage 


declare object _info_$brief entry (ptr, fixed bin(24), ptr, fixed bin(35)); 


call object_info $brief (seg ptr, be, info ptr, code); 


where: 
1. seg ptr (Input) 
is a pointer to the base of the object segment. 
2. be (Input) 
is the bit count of the object segment. 
ce info_ptr (Input) 
is a pointer to the info structure in which the object information 
is returned. See "Information Structure" later in this description. 
4, code (Output) 


is a standard status code. 


Entry: object _info_$display 


This entry point returns, in addition to the information returned in the 
object_info $brief entry point, all the identifying data required by certain 
object display commands, such as the print link info command (described in this 
document). 7 ~ 
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Usage 


declare object_info $display entry (ptr, fixed bin(24), ptr, 
fixed bin(35)); 


call object_info $display (seg ptr, be, info ptr, code); 


where all the arguments are the same as for the object_info $brief entry point 
above. 


Entry: object_info_ $long 


This entry point returns, in addition to the information supplied by the 
object_info $display entry point, the data required by the Multics binder. 
Usage 
declare object_info $long entry (ptr, fixed bin(24), ptr, fixed bin(35)); 
call object_info_$long (seg_ ptr, be, info ptr, code); 


where all the arguments are the same as in the object_info $brief entry point 
above. 


The information structure is as follows (as defined in the system include 
file object_info.inel.pl1): 


del 1 object_info aligned based, 

2 version number fixed bin, 

2 textp ptr, 

2defp ' ptr, 

2 linkp per, 

2 statp pir, 

2 symbp ptr’, 

2 bmapp ptr, 

2 ting fixed bin(18), 

2 ding fixed bin(18), 

2 ling fixed bin(18), 

2 ilng fixed bin(18), 

2 sing fixed bin(18), 

2 bling fixed bin(18), 

2 format, 
3 old format bit(1) unaligned, 
3 -ound bit(1) unaligned, 
3 relocatable bit(1) unaligned, 
3 procedure bit(1) unaligned, 
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standard 
gate 


IW WO) OW WW WW 


pad 
2 entry bound 


Separate static 
links in text 
perprocess static 


object _info_ 


bit(1) 
bit(1) 
bit(1) 


unaligned, 
unaligned, 
unaligned, 
bit(1) unaligned, 
bit(1) unaligned, 
bit(27) unaligned, 
fixed bin, 


2 textlinkp ptr, 
/*This is the limit of the $brief info structure.*/ 
2 compiler char(8) aligned, 
2 compile time fixed bin(71), 
2 userid char(32) aligned, 
2 cvers aligned, 
3 offset bit(18) unaligned, 
3 length bit(18) unaligned, 
2 comment aligned, 
3 offset bit(18) unaligned, 
3 length bit(18) unaligned, 
2 source map fixed bin, 
/*This is the limit of the $display info structure.*#/ 
2 rel _ text ptr, 
2 rel def ptr, 
2 rel_ link ptr, 
2 rel_ static ptr, 
2 rel_symbol ptr, 
2 text_boundary fixed bin, 
2 static boundary fixed bin, 
2 default truncate fixed bin, 
2 optional truncate fixed bin; 
/*This is the limit of the $long info structure.*#/ 
where: 


1. version number 


is the version number of the 

This value is input. 
2. textp 

is a pointer to the base of 
3. defp 

is a pointer to the base of 
4, linkp 

is a pointer to the base of 
5. statp 

is a pointer to the base of 
6. symbp 

is a pointer to the base of 
7/81 7-1 
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the text section. 


the definition section. 
linkage section. 

Static section. 
section. 


symbol 
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7. bmapp 

is a pointer to the break map. 
8. tiling 

is the length (in words) of the text section. 
9. ding 

is the length (in words) of the definition section. 
10. llng 

is the length (in words) of the linkage section. 
11. ilng 

is the length (in words) of the static section. 
12. sling 

is the length (in words) of the symbol section. 
13. bling 


is the length (in words) of the break map. 


14. old format 
fe indicates the format of the segment. 
Wwi"b old format 
“Ob new format 


15. bound 
indicates whether the object segment is bound. 
5) it is a bound object segment 
OME it is not a bound object segment 


16. relocatable 
indicates whether the object is relocatable. 
AL? Blu 6: the object is relocatabie 
BOND the object is not relocatable 


17. procedure 
indicates whether the segment is a procedure. 
witb it is a procedure 
noe D it is nonexecutable data 


18. standard 
indicates whether the segment is a standard object segment. 
m4" it is a standard object segment 
MOND it is not a standard object segment 


19. gate 
indicates whether the procedure is generated in the gate format. 
i Bu 0) it is in the gate format 
MOA it is not in the gate format 


20. separate static 
indicates whether the static section is separate from the linkage 
section. 
alee o static section is separate from linkage section 
NOvD static section is not separate from linkage section 


21. links in text 
indicates whether the object segment contains text-embedded links. 
gat a 9) the object segment contains text-embedded links 
TORS the object segment does not contain text-embedded links 
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22. perprocess static 
indicates whether the static section should be reinitialized for a 
run unit. 
Liat Bae static section is used as is 
HO" b static section is per run unit 


236. pad 
is currently unused. 


24. entry bound 
is the entry bound if this is a gate procedure. 


25. textlinkp 
is a pointer to the first text-embedded link if links_in_text is 
equal to "1"b. 


This is the limit of the info structure for the object_info $brief entry point. 


26. compiler 
is the name of the compiler that generated this object segment. 


27. compile time 
is the date and time this object was generated. 


28. userid ; 
is the access identifier (in the form Person_id.Project_id.tag) of 
the user in whose behalf this object was generated. 


2g. cvers.offset 
is the offset (in words), relative to the base of the symbol 
section, of the aligned variable length character string that 
describes the compiler version used. 


30. ecvers.length ; 
is the length (in characters) of the compiler version string. 


31. comment.offset 
' is the offset (in words), relative to the base of the symbcl 
section, of the aligned variable length character string containing 
some compiler-generated comment. 


32. comment.length 
is the length (in characters) of the comment string. 


33. source map 
is the offset (relative to the base of the symbol section) of the 
source map. 


This is the limit of the info structure for the object_info $display entry 


34. rel _text 
is a pointer to the object's text section relocation information. 


35. rel def 


is a pointer to the object's definition section relocation 
information. 
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36. 


ye 


38. 


39: 


40. 


41. 


42, 


een 


rel 210k 
is a pointer to the object's linkage section relocation information. 


rel static 
is a pointer to the object's static section relocation information. 


rel_ symbol 
is a pointer to the object's symbol section relocation information. 


text boundary 
~ partially defines the beginning address of the text section. The 
text must begin on an integral multiple of some number, e.g., 
O mod 2, O mod 64; this is that number. 


static boundary 
is analogous to text boundary for internal static. 


default truncate 
Is the offset (in words), relative to the base of the symbol 
section, starting from which the symbol section can be truncated to 
remove nonessential information (e.g., relocation information). 


optional truncate 
is the offset (in words), relative to the base of the symbol 
section, starting from which the symbol section can be truncated to 
remove unwanted information (e.g., the compiler symbol tree). 


This is the limit of the info structure for the object_info $long entry point. 
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Name: pl1_io_ 


The pll_io_ subroutine is a collection of utility functions for extracting 
information about PL/I files that is not available within the language itself. 


Entry: pli_io_ $get_iocb_ ptr 


This function returns the I/0 control block pointer for the Multies I/0 
System switch associated with an open PL/I file. This pointer may be used to 
perform control and modes operations upon the switch associated with that file. 


Usage 


declare pl1_io $get_iocb ptr entry (file) returns (ptr); 


iocb_ptr = pl1l_io $get_iocb ptr (file variable); 


where: 


Vs file variable (Input) 
is a PL/I file value. 


2. iocb_ ptr (Output) 
is a pointer to the I/0 control block for the file. 


Notes 


Performing explicit operations via the Multics I/0 System upon switches in 
use by PL/I I/0 is potentially dangerous unless care is taken that certain 
conventions are observed. No calls should be made that affect the data in the 
PL/I data set being accessed, the positioning of the data set, or the status or 
interpretation of any I/O operations that may be in progress. In general, this 
limits such calls to those which obtain status information. 


SRS erence ee a SE ED 


Entry: plil_io_$error_code 


This funetion returns the last nonzero status code encountered by PL/I I/0 
while performing file operations. This is a standard Multics status code and 
describes the most recent error more specifically than the PL/I condition which 
is raised after an error. 
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Usage 


declare pl1l_io $error_code entry (file) returns (fixed bin(35)); 


code = pll_io $error_code (file variable); 


where: 
les file variable (Input) 
is a PL/I file value. 
2. code (Output) 
is the last nonzero status code associated with the file... 
Notes 


The specific values returned by this function are subject to change. See 
"Handling Unusual Occurrences" in Section 7 of the MPM Reference Guide. 
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Name: prepare _mce_restart 


The prepare mc_restart subroutine to checks machine conditions for 
restartability, and makes modifications to the machine conditions (to accomplish 
user modifications to process execution) before a condition handler returns. 


The prepare mc_restart_ subroutine should be called by a condition handler, 
which was invoked as a result of a hardware-detected condition, if the handier 
wishes the process to: 

Ty retry the faulting instruction 


cae skip the faulting instruction and continue 


Ss; execute some other instruction instead of the faulting instruction and 
continue 
4, resume execution at some other location in the same program 


When a condition handler is invoked for a _ hardware-detected condition, it 
is passed a pointer to the machine-conditions data at the time of the fault. If 
the handler returns, the system attempts to restore these machine conditions and 
restart the process) at the point of interruption encoded in the 
machine-conditions data. After certain conditions, however, the hardware is 
unable to restart the processor. In other cases, an attempt to restart always 
causes the same condition to occur again, because the system software has 
already exhausted all available recovery possibilities (e.g., disk read errors). 


Entry: prepare_mc_restart $retry 


This entry point is called to prepare the machine conditions for retry at 
the point of the hardware-detected condition. For example, this operation is 
appropriate for a linkage error signal, resulting from the absence of a segment, 
that the condition handler has been able to locate. 


Usage 


declare prepare mc_restart $retry entry (ptr, fixed bin(35)); 


call prepare _mc_restart $retry (mc_ptr, code); 


where: 
1. me_ptr (Input) 

is a pointer to the machine conditions. 
2. code (Output) 


is a standard status code. If it is nonzero on return, the machine 
conditions cannot be restarted. See "Notes" below. 
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Entry: prepare_me_ restart $replace 


This entry point is called to modify machine-conditions data so that the 
process executes a specified machine instruction, instead of the faulting 
instruction, and then continues normally. 


Usage 


declare prepare _me_restart $replace entry (ptr, bit(36), fixed bin(35)); 


call prepare _me_restart_$replace (mc_ptr, new_ins, code); 


where: 
V3 me ptr (Input) 
is as above. 
2a new_ins (Input) . 
is the desired substitute machine instruction. 
3. code (Out put ) 


is as above. 


Entry: prepare mc restart $tra 


Thie antwrwu nnint te AnTT AA Fn maAaAsa Fir manhina RaAanATeS AN em AREA ean thant tha 
2ishOo Chibi Y PUAIIYL bo vCasivcu vy mWVUauLl y HaVML oS CVUNMULLLVIDOD Uablda oY” LiIlauv ULI 
process resumes execution, taking its next instruction from a_ specified 
location. The instruction transferred to must be in the same segment that 
caused the fault. 
Usage 
declare prepare_mc_restart $tra entry (ptr, ptr, fixed bin(35)); 
call prepare mc_restart $tra (mc_ptr, newp, code); 
where: 
1. me_ptr (Input) 
is the same as in the prepare mc_restart $retry entry point above. 
2. newp (Input) 
is used in replacing the instruction counter in the machine 
conditions. 
3. code (Out put ) 


is the same as in the prepare mc_restart $retry entry point above. 
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Notes 


For all entry points in the prepare mc restart _ subroutine, a pointer to 
the hardware machine conditions is required. The format of the machine 
conditions is described in "Multics Condition Mechanism" in Section 7 of the MPM 
Reference Guide. 


For all entry points in the prepare_mc_restart_ subroutine, the following 
codes can be returned: 


error_table $badarg an invalid me_ptr was provided 
error_table $no_restart the machine conditions cannot be restarted 
error _table $bad_ ptr the restart location is not accessible 


error table $useless restart the same error will occur again if restart 
is attempted 
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Name: read allowed_ 


The read allowed function determines whether a subject of specified 
authorization has access (with respect to the access isolation mechanism) to 
read an object of specified access class. For information on access classes, 
see "Nondiscretionary Access Control" in Section 6 of the MPM Reference Guide. 


Usage 


declare read _allowed_ entry (bit(72) aligned, bit(72) aligned) returns 
(bit(1) aligned); 


returned bit = read allowed (authorization, access class); 


where: 
1. authorization (Input) 

is the authorization of the subject. 
2 access class (Input) 

is the access class of the object. 
3. returned bit (Output) 


indicates whether the subject is allowed to read the object. 
ua Gals) read is allowed 
MOND read is not allowed 
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Name: read password 


The read password subroutine reads a single line from the users' terminal 
(actually from the user input I/O switch). It attempts to hide the input line 
by turning the printing mechanism off before reading and turning it back on 
afterwards. If the printing mechanism cannot be turned off, then a mask 
consisting of several layers of printing designed to "black out" the page is 
printed. One of the layers of printing is pseudo-randomly generated so that it 
will be different each time the subroutine is called, thus making it difficult 
to analyze the layers of overprinting. The mask is 12 characters long. 


Usage 


declare read_ password entry (char(*), char(*)); 


call read_password_ (prompt, password); 


where: 

13 prompt (Input) 
is a message to be printed before the password is read. It can be 
any length. A newline character is always printed after the 
prompting message. 

ne password (Output) 
is the password that the user typed. It can be up to 120 characters 
long. 

Note 

The password is processed as follows: Tab characters are translated to 


blanks. Leading blanks are removed. Characters after any embedded blanks are 
removed. If the resulting password is all blank, a single asterisk ("*") is 
returned, otherwise the password is returned. 
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‘Entry: read password $switch 


This entry is similar’ to read password , but it allows the caller to 
specify the I/O switches to be used to print the prompt and read the password. 


Usage 


declare read password $switch entry (ptr, ptr, char(*), char(*), 
fixed bin(35)); 


call read password $switch (output switch, input switch, prompt, password, 


code); 

where: 

16 output switch (Input) 
is a pointer to the I/O switch on which the prompt, and if necessary 
the password mask, is printed. 

ee input switch (Input) 
is a pointer to the I/O switch from which the password is read. 

3. prompt (Input) 
is a message to be printed before the password is read. It can be 
any length. A newline character is always printed after the 
prompting message. 

4. password (Output) 
is the password that the user typed. It can be up to 120 characters 
long. 

5. code (Output) 
is a standard system status code which is non-zero only if a 
password could not be read. 


Note 


The password is’ processed as follows: Tab characters are translated to 
blanks. Leading blanks are removed. Characters after any embedded blanks are 
removed. If the resulting password is all blank, a single asterisk ("*") is 
returned; otherwise the password is returned. 
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Name: read _ write allowed_ 


The read write allowed function determines whether a subject of specified 

authorization has access (with respect to the access isolation mechanism) to 
‘read and write an object of specified access class. For information on access 
classes see "Nondiscretionary Access Control" in Section 6 of the MPM Reference 
Guide. 


Usage 


declare read write allowed _ entry (bit(72) aligned, bit(72) aligned) 
returns (bit(1) aligned); 


returned bit = read_write allowed _ (authorization, access class); 


where: 
jue authorization (Input) 
is the authorization of the subject. 
2. access class (Input) 
is the access class of the object. 
3. returned bit (Out put) 
indicates whether the subject is allowed to both read and write the 
object. 


ae Ed 9) read and write are allowed 
"OND read and write are not allowed 
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Name: release area_ 


The release _area_ subroutine cleans up an area after it is no longer 
needed. If the area is a segment acquired via the define area subroutine, the 
segment is released to the free pool via the temporary segment manager. If the 
area was not acquired (only initialized) via the define area subroutine then 
the area itself is reinitialized to the empty state. In certain cases when the 
area is defined by the system or when the area is extended in ring 0, the 
temporary segment manager is not used and the area segments are actually created 
and deleted. Segments acquired to extend the area are released to the free pool 
of temporary segments or deleted if they are not obtained from the temporary 
segment manager. 


Usage 


declare release area_ entry (ptr); 


call release _area_ (area_ptr); 


where area ptr (Input/Output) points to the area to be released. 


Note 


The release_area_ subroutine sets area ptr to nuili after copying it to a 
local variable. 
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Name: requote string 


requote string __ 


The requote string subroutine doubles all quotes within a character string 


and returns the result enclosed in quotes. 


Usage 


declare requote string entry (char(*)) returns(char(*)); 
requoted string = requote string (string); 
where: 


Ts string (Input) 
is the string to be requoted. 


2.  requoted string (Output) 


is the string with all quotes doubled and enclosed in quotes. 


Examples 


Within = requote string _ ("al) 


WIE Stl tee tp te et te = requote string _~ (Yaittpi) 
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-Name: resource control 


The resource control subroutine provides an interface to the Multics resource. 
control facility. Entry points in this subroutine allow programs to reserve or 
cancel I/O devices and volumes. 


Note 


Not all sites enable the resource control subroutine. Consult your system 
administrator to find out if your site has this capability. 


AR SE EE I I A LE LEI TTD 


Entry: ‘resource control $reserve 


This entry point reserves a resource or group of resources for uSe by a 
process. 


Usage 


declare resource control $reserve entry (pointer, pointer, bit (1) aligned, 
bit (72) aligned, fixed bin (35)); 


call resource control $reserve (descriptions ptr, reservation dese ptr, 
authorization, system, code); 


where: 


4. descriptions ptr (Input) 
is a pointer to the structure containing a description of the resources 
to be reserved (see "Resource Description" below). 


2. reservation dese ptr (Input) 
is a pointer to the structure containing reservation information for 
the resources to be reserved (see "Reservation Description" below). 


3. authorization (Input) 
checks the user's authorization to use the devices or volumes and is 
only valid if system = "1"b. 


4, system (Input) 
specifies, if "1"b, that the calling process wishes to perform a 
privileged reservation (see "Notes" below). 


5. code (Output) 
is a standard status code. 
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rvation Description 


The reservation dese ptr argument points to the following structure (declared 


he include file resource control dese.inel.pl1): 
del 1 reservation description aligned based, 
2 version no fixed bin, 
2 reserved for char (32), 
2 reserved by char (32), 
2 reservation id fixed bin (71), 
2 group starting time fixed bin (71), 
2 asap duration ~ fixed bin (71), 
2 flags aligned, 
(3 auto expire bit (1), 
3 asap bit (1), 
3 rel bit (1), 
3 sec bit (1)) unaligned, 
-2n items fixed bin, 
2 reservation group (Resource count refer 
(reservation description.n items)), 
3 starting time fixed bin (71), 
3 duration | fixed bin (71); 
e: 
version no (Input) 
“is the current version number of this structure. It should be set 
to "resource control version 1". 
reserved for (Input) 
Specifies the User id of the process for whom this reservation is 
‘made. The use of an asterisk (*) for a component name is permitted. 
If this element is blanks, the User id of the current process is 
used. 7 
reserved by (Input) 
Is the User id of the process which is charged for this reservation 
(see "Notes™ below). This element is ignored for an unprivileged 
reservation and the current User id is used. 
reservation id (Input or Output) 
is an identifier for this reservation group. It is currently returned 
as an absolute clock time. 
n_items (Input) 


is the number of items being reserved. 


rest of the items in this structure are currently ignored and should be set 
ero. 
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Notes 


-If system = "1"b, reservation description.reserved by is used to specify 
the User _id of the process to be charged for this reservation. 


The reservation description structure is strongly dependent on _ the 
resource descriptions structure. That is, for each resource described in 
resource descriptions there must be a corresponding entry of the same index in 
reservation description. 


-Access Restrictions 

Execute access to the rep sys- gate is necessary to perform a privileged 
reservation. 
Entry: resource control $cancel 


This entry point cancels the reservation of a resource or group of resources. 


Usage 


declare resource control $cancel id string entry (char(*), char(*), 
bit(1) aligned, fixed bin (35)); 


call resource control $cancel id string (reservation id, group id, system, 


code); 
where: 
1. reservation id (Input) 
is the character string representation of the reservation identifier 
to be cancelled. 
2. group id (Input) 
~ is the group id of the user to whom the reservation belongs. This 
is only valid if system = "1"b. 
3. system (Input) 
specifies, if "1"b, that a privileged cancellation is to be performed 
(see "Notes" below). 
4. code (Output) 


is a standard status code. 
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Notes 


If system = "1"b, then the reservation group is forcibly cancelled whether % 
or not it belongs to the current process. 


Access Restrictions 


Execute access to the rep _sys_ gate is necessary to perform a privileged 
eancellation. 


ULSe.. 7-182. 3 AK92D 


7/82 


This page intentionally left blank. 


7-182.4 


This page intentionally left blank. 


7/82 7-182.5 AK92D 


This page intentionally left blank. 


7/82 - 7-182.6 AK92D 


This page intentionally left blank. 


7/82 - 7-182.7 AK92D 


This page intentionally left blank. 


7/82 © 7-182.8 AK92D 


resource control | resource control | 


Resource Description 


The descriptions ptr argument points to the following structure (this 


structure is declared in the include file resource control desc.incl.pl1): 


del 1 resource descriptions based (resource dese ptr) aligned, 
version no fixed bin, 
n_items fixed bin, 
item (Resource count refer (resource descriptions.n items)) aligned, 
type char (32), 
name char (32), 
uid bit (36), 
potential attributes bit (72), 
attributes (2) bit (72), 
desired attributes (4) bit (72), 
potential aim range (2) bit (72), 
aim_range (2) bit (72), 
owner char (32), 
acs path char (168), 
location char (168), 
comment char (168), 
charge type char (32), 
rew bit (3) unaligned, 
(usage lock, 
release lock, 
awaiting clear, 
user_alloc) bit (1) unaligned, 
pad2 bit (29) unaligned, 
given aligned, 
(4 (name, 
uid, 
potential attributes, 
desired attributes, 
potential aim range, 
aim range, 
owner, 
acs path, 
location, 
comment, 
charge type, 
usage lock, 
release lock, 
user_alloc) bit (1), 
4 pad1 bit (22)) unaligned, 
3 state bit (36) aligned, 
3 status_code fixed bin (35); 


No Po Po 


WW WOW WW WW Wd WW WW WWW do 


QU a 


where: 

1. version no (Input) 
is the current version number of the structure. It should be set to 
"resource control version 1". 

2. n_items (Input) 
Specifies the number of resources described by this structure. A 
consistent combination of the following elements must be supplied 
for each resource described. 

12/79 7-182.9 AK92A 


resource control | resource control _ 


15 


TT 


125 


13. 


type (Input) 
specifies the type of resource desired (e.g., tape, disk drive). It 
must be supplied (see "Notes" below). 


name (Input or Output) 
is a specific resource name. If flags.name given = "1"b, the named 
resource is chosen. If flags.name given = "0"b, a resource is 


chosen depending on criteria specified by. other elements of the 
structure, and the name of the resource chosen is returned in this 
element (see "Notes" below). 


uid (Input or Output) 
is the unique identifier of a specific resource. Lf 
flags.uid given = "1"b, the specified resource is chosen. If 
flags.uid given = "O"b, a resource is chosen depending on criteria 


specified by other elements of the structure, and the unique 
identifier of the resource chosen is returned in this element. 


potential attributes (Output) 
specifies the potential attributes of the resource chosen. 


attributes (Input or Output) 
contains, if flags.attr_ given = "1"b, the specification of 
attributes which the resource chosen must possess. If 
flags.attr_ given = "O"b, the resource to be chosen need not possess 
any particular attributes. The attributes of the resource chosen 
are returned in these elements (see "Notes" below). 


desired attributes (Input) 
specifies the desired attributes of the resource chosen. 


potential aim bounds (Output) 
are a pair of AIM access classes, specifying the minimum and maximum 
process authorization that can be permitted to acquire this 
resource, 


aim_bounds (Input or Output) 
are a pair of AIM access classes, specifying the minimum and maximum 
process authorization that can be permitted to both read and write 
this resource. If flags.aim_bounds given = "1"b, this element is 
input. Otherwise, it is output. 


owner (Input or Output) 
is the owner of the resource. If flags.owner = "1"b, this element 
is: input. Otherwise, this element is output (see "Notes" and 


"Access Restrictions" below). 


acs path (Input) 
is the pathname of the access control segment (ACS) for this 
resource (see "Access Restrictions" below). 


location (Output) 
contains a character string description of the location of this 
resource. . 
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comment (Input) 
contains a character-string comment wnichn is associated with this 
resource. 

charge type (Input) 


is the accounting identifier for this resource. 


rew (Output) 
is the effective access of the user to this resource. 


usage lock (Input) 
if "1"b, specifies that this resource cannot be used by any user, 
regardless of the state of the resource. 


release lock (Input) 
if "1"b, specifies that the owner of the resource is not allowed to 
release the resource. Unless system = "1"b, this element is ignored 


(see "Notes" below). 


awaiting clear (Output) 
Specifies that the resource iS awaiting manual clear. 


user_alloc (Input) : 
if "1"b, specifies that the user has not allocated the resource to 
any use. 

pad2 (Input) 


is unused and must be zero. 


name (Input) 
is "1"b if item.name has been supplied by the caller. 


uid (Input) 
is "1"b if item.uid has been supplied by the caller. 

potential attr (Input) . 
is "i"b, if item.potential attributes has been supplied by the 
caller. 

desired attr (Input) 


is "1"b if item.desired attributes has been supplied by the caller. 
potential aim_bounds (Input) 
is "i"b if item.potential aim_bounds has been supplied by the 
caller. 


aim_bounds (Input) 
is "1"b if item.aim_ bounds has been supplied by the caller. 


owner (Input) 
is "i"b if item.owner has been supplied by the caller. 


acs path (Input) 
is "i"b if item.acs path has been supplied by the caller. 


location (Input) 
is "1"b if item.ilocation nas been supplied by the caller. 


comment (Input) 
is "1"b if item.comment has been supplied by the caller. 
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32. charge type (Input) 
is "1"b if item.charge type given has been supplied by the caller. 
33. usage lock (Input) 
is "1"b if item.usage lock has been supplied by the caller. 
34. release lock (Input) 
is "1"b if item.release lock has been supplied by the caller. 
35. user alloc (Input) 
is "1"b if item.user_alloc given has been supplied by the caller. 
36. padi (Input) 
is unused and must be zero. 
37. state (Output) 
is for the use of resource control and should not be used by the 
user. 
38. status code (Output) 
is a standard status’ code. If the subroutine argument code is 
nonzero, one or more items in the structure have a nonzero 
Status _ code specifying in more detail why the attempt to manipulate 
the described resource was refused. 
Notes 


A list of defined resource types may be obtained via the 
list_resource types command. 


Suitable values for the attributes element may be constructed using the 
cv rep attributes $from_ string subroutine. 


Access Restrictions 


The user must have at least sm permission to the directory in which the ACS 
is specified to reside. 


Unless otherwise stated, the user must have re access to the rep sys_ gate 
to specify system = "1"b in the calling sequence for any entry point of the 
resource control_ subroutine. 
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Name: resource info_ 


The resource info _ subroutine returns selected information about RCP 
resource types defined on the system. 


Entry: resource info $get_type 


This entry point, given the name of a resource type, indicates whether the 
resource type named is a device or a volume. 


Usage 


geclare resource info $get type entry (char (*), bit (1), fixed bin (35)); 


call resource info $get_type (mame, is_volume, code); 


where: | 
1. name — * (Input) 
is the name of a defined resource type (see "Notes" below). 
2 is_volume (Output) 
is "1"b if the resource type given specifies a class of volumes. If 
"O"b, the resource type given specifies a class of devices. 
3. code . (Output) 
is a standard status code. 
Notes 


A list of defined resource types may be obtained via the 
list_resource types command (see Section 4). 


Entry: resource info $limits 


This entry point returns information about quantity and time limits for a 
given resource type. 
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Usage 


declare resource info $limits entry (char (*), fixed bin, fixed bin, 
fixed bin, Fixed bin (35)); 


call resource info $limits (name, max quantity, default time, max time, 


code); 
where: 
1. name (Input) 
is the name of a defined resource type. 
2.. max quantity (Output) 
is the maximum number of this type of resource that a process may 
assign at one time. 
3. default time (Output) 
Is the default reservation time, in minutes, for this type of resource. 
4, max time (Output) 
- is the maximum allowed reservation time, in minutes, for this type 
of resource. 
5. code (Output) 
is a standard status code. 
Notes 


The information returned by this entry point is from the RTDT. These are 
not the limits currently enforced by RCP (see "Device Limits" in Section 1 of 
the Multics Resource Control Users' Guide (CT38)). 


' Entry: resource info $mates 


This entry provides information about the resource type or types with which 
the given resource type may be mounted. 
Usage 


declare resource info $mates entry (char (#*), fixed bin, char (*) 
dimension (¥), fixed bin (35)); 


call resource info $mates (name, n_mates, mates, code); 


where: 

‘Le name (Input) 

is the name of a defined resource type. 
2. n_mates (Output) 


is the number of mates returned. 
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Bs mates (Output) 
contains the name or names of the resource type(s) that may be 
mounted with this resource (see "Notes" below). 


4, code (Output) 
is a standard status code. 


Notes 


If the number of elements in mates is too small to hold all the mates for 
the given resource type, code is set to error table $smallarg and mates is set 
to the null string. However, n mates still contains the number of mates 
associated with the given resource type. 


Entry: resource info $defaults 


This entry point fills a resource descriptions structure with the default 
registration parameters defined in the RTDT. 


Usage 


del resource info $defaults entry (char(*), char(*), pointer, 
fixed bin(35)); 


call resource info $defaults (name, subtype, item_ptr, code); 


where: 
Te name (Input) 

is the name of a defined resource type. 
]. subtype (Input) 


is the name of a subtype of the resource type, defined in the RTDT. 
If subtype is the null string, the master defaults for the resource 
type are used. 


3. item_ptr 
points to a structure declared like resource descriptions.item (see 
the resource control_ subroutine). 


4, code (Output) 
is a standard status code. 
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Entry: resource info $lock on release 


This ‘entry point returns a value specifying whether resources of a given 
type are to be locked for manual clearing at release time. 


Usage 


del resource info $lock on release entry (char(*), bit(1) aligned, 
fixed bin(35)); 


call resource info $lock on_release (name, lock sw, code); 


where: . 
Vs name (Input) 
is the name of a defined resource type. 
2s lock sw (Output) 
~ specifies whether the resource is locked at release time. 
"1"b lock the resource 
"O"™b do not lock the resource 
ce code | (Output) 


is a standard status code. 


Entry: resource info $canonicalize name 


This entry point applies the proper canonicalization to a resource name of 
a given resource type. See "Canonicalization Routines" in the Multics 


_§ Administrators' Manual - Resource Control (Order No. CC74). 


Usage 


declare resource info $canonicalize name entry (char(*), char(*), char(*), 
fixed bin(35)); 


call resource info $canonicalize name (resource _type, resource name, 
eanonicalized name, code); 
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where: 
le resource type (Input) 
is the name of a defined resource type. 
Ove resource name (Input) 
is the string to be canonicalized. 
3% canonicalized name (Output) 
is the canonicalized representation of resource name. 
4, code (Output) 


is a standard status code. 
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Name: run 


The run_ subroutine manages the environment for a run unit and invokes the 
main program of a run unit. See the documentation of the run command in the MPM 
Commands for an explanation of run units. 


Entry: run_ 


This entry sets up the run unit environment, invokes the main program, and 
restores the environment when the run ends. 


Usage 


declare run_ entry (entry, ptr, ptr, fixed. bin(35)); 


call run_ (main_entry, arglist ptr, run_cs ptr, code); 


where: 
Vs main_entry (Input) 
is the entry point to be called as the main program of the run unit. 
2. arglist ptr (Input) 
points to the argument list for the main program. 
3. run_cs ptr (Input) 


points to the following structure which is declared in 
run_control structure.incl.pli: 


del 1 run_control_ structure aligned based(run_cs ptr), 
2 version fixed bin, 
2 flags aligned, 
3 ec bit(1) unaligned, 
3 pad bit(35) unaligned, 
2 reference name switch fixed bin, 
2 time limit fixed bin(35); 
where: 
1. version 


is the version number of the structure. It should be 
set to run_control structure version 1. 


is "1"b if the main program is exec com (main entry must 
Still be set), otherwise ec must be "0O"b, 


a 


run run 


3% pad 
must be "O"b. 


4, reference name switch 
is set to one of the named constants 
NEW REFERENCE NAMES, COPY REFERENCE NAMES or 
OLD REFERENCE NAMES delcared in 
run_control structure.incl.pli. 

om time limit 
is the interval in cpu seconds after which the program 
is to be interrupted. 


7 code (Output) 
is a standard status code, 
Entry: run $environment_ info 


This entry enables the symbolic debugging tools to obtain the saved stack 
header information used by a given stack frame. 


Usage 


declare run _$environment_info entry (ptr, ptr, fixed bin(35)); 


call run_$environment info (stack frame ptr, info ptr, code); 


where: 
he stack frame ptr (Input) 
points to an active stack frame on the current stack. 
o% info ptr (Input) 
points to the following structure, declared in env_ptrs.incl.pll: 
del 1 env_ptrs aligned based, 
2 version fixed bin, 
2 pad fixed bin(35), 
2 lot_ptr ptr, 
2 isot_ptr ptr, 
eo CL per ptr, 
2 combined stat pir ptr, 
2 user free ptr ptr, 
2 sys_link info _ptr ptr, 
2 rnt_ptr ptr, 
2 sct_ptr DUrs 
where: 
en version 
is the version number of this structure; it must be 1. 
2. pad 


is unused. 
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3 code 


run 


Lot. ptr 
points to the linkage offset table (LOT). 


isot_ ptr 
points to the internal static offset table (ISOT). 


clr ptr 
points to the area where linkage sections are allocated. 


combined stat _ptr 
points to the area where separate static sections are 
allocated. 


user free ptr 
points to the area where user storage is allocated. 


sys _link_info ptr 
points to the control structure for external static 
variables. ‘ 


rnt_ptr 
points to the reference name table. 


sct_ptr 
points to the static handler array. 


(Output) 


is a standard system status code. 
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Name: sct_manager_ 


The sct manager _ subroutine manipulates the System Condition Table (SCT), 
which is used to provide static handlers for certain conditions. It has entries 
to set a handler, get a pointer to a handler, and call a handler if one exists. 


Entry: sct_manager_$set 


This entry point sets the handler for the given index to the one given in 
the call. 


Usage 


declare sct_manager $set entry (fixed bin, ptr, fixed bin (35)); 


eall sct_manager $set (fcode, hptr, code); 


where: 

Te feode (Input) 
is a fixed binary index into the SCT table. Appropriate values can 
be selected from static _handlers.inel.pl1, which gives symbolic 
names for all indices currently defined. 

2. hptr (Input) 
is a pointer to the static handler, if it exists. 

Big code (Output) 


is a standard status code. 


Entry: sct_manager $get 


This entry point returns a pointer to the handler for the given index, or 
null if it does not exist. 


Usage 


declare sct_manager _$get entry (fixed bin, ptr, fixed bin (35)); 


call sect_manager $get (fcode, hptr, code); 
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where: 

1. fcode 
2. hptr 
as code 


sct_manager_ 


(Input) 
is a fixed binary index into the SCT table. Appropriate values can 
be selected from static handlers.inel.pl1, which gives symbolic 
names for all indices currently defined. 


(Output) 
is a pointer to the static handler, if it exists. 


(Output) 
is a standard status code. 


Entry: sct_manager_$call_handler 


This 
"continue" bit is set on to pass this information to the caller. 


Usage 


declare 


entry point calls a handler if it exists. If none exists, the 


sct_manager_$call_handler entry (ptr, char(*), ptr, ptr, bit (1) 


aligned); 


call scet_manager_ $call_ handler (mcptr, cname, null(), null(), continue); 


where: 

Ts meptr (Input) 
is a pointer to the machine conditions for the condition to be 
handied. The fault code within the scu data determines the handler 
to use. 

2 cname (Input) 
is the name of the condition being signalled. It is passed to the 
condition handler, if there is one. 

Bs continue (Output) 
is set to *i"p if there is no handier, otherwise it is set by the 
handler. 

The third and fourth arguments are ignored; they must be null. They are 


declared for compatibility with the standard condition handler mechanism. 


7/81 
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Notes 


The System Condition Table is a based array of 127 packed pointers, pointed 
to by the sect pointer in the stack header of the stack for the ring in which 
set_manager_ is executing. The pointers point to the entry to call, and a null 
value is used for the environment portion of the entry. A static handler has 
the same calling sequence as any other condition handler. SCT indices are 
assigned by hardcore systems programmers. Since sct_manager_$call_ handler uses 
machine conditions to locate the handler, conditions without machine conditions 
(e.g., software conditions such as PL/I support) cannot have static handlers. 
Ring 0, rather than the user, ensures that there is a proper fault code in the 
conditions. 


7/81 7-182.23 AK92C 


set ext variable | oe set_ext_variable_ 
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Name: set ext variable 


The set’ ext variable subroutine allows the caller to look up an external 
variable by name. If the name is not found, the variable is added to the list 
of external variables. 


Usage 
ae set ext variable entry (char(*), ptr, ptr, bit(1) aligned, ptr, 
fixed bin(35));_ 


ear set_ext variable (ext name, init_info ptr, sb ptr, found sw, 
‘node ptr, code); 


where: 
1s ext_name (Input) 

is the name of the external variable. 
2. init info ptr (Input) 

is a pointer to the initialization info (see "Notes" Boren) 
3. sb ptr (Input) 

a is a pointer to the base of the stack of the caller. 

4, found sw (Output) 

is set to indicate whether the variable was found or not. 
5. node ptr. (Output) 

is a pointer to the external variable node. (see "Notes" below) 
6. code (Output) 

is an error code. 
Notes 


initialized. The following structure, described in 
system link init _info.incl.pl1, is pointed to by init info ptr: 


When a new external variable is allocated (not found), it must be 


del 1 init info aligned based, 
2 size fixed bin(19), 
2 type fixed bin, 
2 init template 


(init size refer 
(init _info.size)) fixed bin(35); 
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where: 
1 size 

is the initialization template size, in words. 
2. type 


is the type of initialization to be performed. 
O no init 

3 init from template 

4} init area to empty () 


ce init template 
~ is the initialization template to be used when type = 3. Great care 
should be taken when referencing with the node ptr. The node 
structure should never be modified. Modifications to the node will 
have unpredictable results. 


Notes 


A pointer to the following structure is returned by the locate entry to 
set_ext variable (found in system _link names.inel.pl1): 


del 1 variable node based aligned, 
2 forward thread ptr unal, 
2 vbl size fixed bin(23) unal, 
2 init type fixed bin(11) unal, 
2 time allocated fixed bin(71), 
2 vbl ptr ptr, 
2 init ptr . ptr, 
2 name size fixed bin, 
2 name char (nehars refer (variable node.name size)); 
where: 


1. forward thread 
is used by the linker to thread this variable to the next. 


2. vbl size 
~ is the size, in words, of this variable. 


3. init type 
~ dis the type of initialization that is performed: 
O none 
3 initialize from template 
4} initialize to an empty area 


4. time allocated 
~ dis the clock reading at the time this variable was allocated. 


5 vbl ptr 
= is a pointer to the variable's storage. 
6. init ptr 
is a pointer to the initialization template. 


7. mame size 


is the number of characters in the variable name. 
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8. name 
is the name of the variable. 
Entry: set ext variable $locate 


This entry point locates the specified external variable and returns a 
pointer to the structure describing the variable. 


Usage 


del set_ext variable $locate entry (char(*), ptr, ptr, fixed bin(35)); 


call set_ext variable $locate (ext_name, sb ptr, node ptr, code); 


where: 
Ts ext name (Input) 
- is the name of the external variable. 
2. sb_ptr (Input) 
is a pointer to the base of the stack of the caller. 
3. node pointer (Output) 
is a pointer to the variable node describing the specified variable. 
This structure is defined in the system link names.incli.pl1 include 
file. (see "Notes" above) = = 
4, code (Output) 


is an error code, 
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Name: shes $set_force write limit 


The shes $set force write limit entry point sets the write limit of the 
calling process. This limit specifies the maximum number of pages that may be 
queued for I/O at the same time by calls to hes $force write. The default for 
this limit is,1. ia 7 


Usage 


declare shes $set_force write limit entry (fixed bin, fixed bin (35)); 


call shes $set_force_write_limit (npages, code); 


where: 

1. npages (Input ) 
is the maximum number of pages that will be allowed to be queued for 
I/O at the same time. 

Cs code (Out put) 


is a standard system status code. 
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Name: signal_ 


The signal Subroutine signals the occurrence of a given condition. A 
description of the condition mechanism and the way in which a handler is invoked 
by the signal Subroutine is given in the "Multics Condition Mechanism" in 
Section 7 of the MPM Reference Guide. 


Usage 


declare signal_ entry options (variable); 


call signal _ (name, mc_ptr, info ptr, we ptr); 


where: 


ie name (Input) 
is the name (declared as a nonvarying character string) of the 
condition to be signalled. 


oe me ptr (Input) 
= is a pointer (declared as an aligned pointer) to the machine 
conditions at the time the condition was raised. This argument is 
used by system programs only in order to signal hardware faults. In 
user programs, this argument should be null if a third argument is 
Supplied. This argument is optional. 


Ss info_ptr (Input) 

is a pointer (declared as an aligned pointer) to information 
relating to the condition being raised. The structure of the 
information is dependent upon the condition being signalled; 
however, conditions raised with the same name should provide the 
information in the same structure. All structures must begin with a 
Standard header. The format for the header as well as the 
Structures provided with system conditions are described in "List of 
System Conditions and Default Handlers" in Section 7 of the MPM 
Reference Guide. This argument is intended for use in signalling 
conditions other than hardware faults. This argument is optional. 


4, we ptr 
a is a pointer (declared as an aligned pointer) to the machine 
conditions at the time a lower ring was entered to process a fault. 
This argument is used only by the system and only in the case where 
a condition that occurred in a lower ring is being signalled in the 
outer ring and when the lower ring has been’ entered to process a 
fault occurring in the outer ring. This argument is optional. 


Notes 


If the signal _ subroutine returns to its caller, indicating that the 
handler has returned to it, the calling procedure should retry the operation 
that caused the condition to be signalled. 
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The PL/I signal statement differs from the signal_ subroutine in that the 
above parameters cannot be provided in the signal statement. Also, for 
PL/I-defined conditions, a call to the signal _ subroutine is not equivalent to a 


PL/I signal statement Since information about these conditions is kept 
internally. . 
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Name: sub err 


The sub err subroutine is called by other programs that wish to report an 
unexpected situation without usurping the calling environment's responsibility 
for the content of and disposition of the error message and the choice of what 
to do next. The caller specifies an identifying message and may specify a 
status code. Switches that describe whether and how to continue execution and a 
pointer to further information may also be passed to this subroutine. The environment 
thet invoked the subroutine caller of sub err may intercept and modify the 
‘standard system action taken when this subroutine is called. 


General purpose subsystems or subroutines, which can be called in a variety 
. of I/0 and error handling environments, should report the errors they detect by 
calling the sub_err_ subroutine. 


Usage 


declare sub _err_ entry options (variable); 


call sub _err_ (code, name, flags, info ptr, retval, etl string, ioa args); 


where: 

1% code (Input) 
is a standard status code describing the reason for calling the 
sub err _ subroutine. (It is normally declared fixed bin(35); but it 
can be any computational data type. If not fixed bin(35), it will 
-be converted to fixed bin(35)). 

2. name (Input) 
is the name (declared as anonvarying character string) of the subsystem 
or module on whose behalf the sub_err_ subroutine is called. 

- 3. flags (Input) 


describe options associated with the error. The flags argument should 
be declared as a nonvarying bit string. The following values, located 
in the include file sub _err flags.incl.pl1, are permitted: 


ACTION CAN RESTART init ("'b) 
ACTION CANT RESTART init ("1"b), 
ACTION DEFAULT RESTART init ("01"b), 
ACTION QUIET RESTART init ("001"b) 
ACTION SUPPORT SIGNAL init ("0001"b)) bit (36) aligned 
~ = internal static options (constant); 


Each bit corresponds to one of the action flags in the standard 
condition info header structure, declared in 
condition info header.inel.pl1. If multiple bits are on in the supplied 
String, all the specified flags are set. See the MPM Reference 
Guide for definitions of the flags. 
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yy, info ptr (Input) 

~ is a pointer (declared as an aligned pointer) to optional information 
specific to the situation. This argument is used as input to initialize 
info.retval (see "Info Structure," below). The standard system 
environment does not use this pointer, but it is provided for the 


convenience of other environments. 


5. retval (Input/Output) 
is a return value from the environment to which the error was reported. 
This argument is used as input to initialize info.retval (see "Info 
Structure," khelow). The standard system environment sets this value 
to zero. Other environments may set the retval argument to other 
values, which may be used to select recovery strategies. The retval 
argument should be declared fixed bin(35). 


6. etl string (Input) 
et is an ioa format control string (declared aS a nonvarying character 
string) that defines the message associated with the call to the 
sub err subroutine. Consult the description of the ioa subroutine 
in the MPM Subroutines. a 


Ta ioa args (Input) 
~ are any arguments required for conversion by the etl string argument. 


Note 


There is an obsolete calling sequence to this subroutine, in which the 
flags argument is a character string instead of a bit string. In that calling 
sequence, the legal values”~ are nel for ACTION CAN RESTART, va for 
ACTION CANT RESTART, gt for ACTION QUIET RESTART, ~ and Wott for 
ACTION DEFAULT RESTART. ~ = 


Operation 


The sub err subroutine proceeds as follows: the structure described below 
is filled in from the arguments to the sub err subroutine and the signal 
subroutine is called to raise the sub _error_ condition. = 


When the standard system environment receives a sub error. signal, it prints 
a message of the form: rs 


name error by sub name;location 
Status code message. Message from ctl string. 


The standard environment then sets retval to zero and returns, if the value 
ACTION DEFAULT RESTART is specified; otherwise it calls the listener. If the 
Start command is invoked, the standard environment returns to sub err , which 
returns to the subroutine caller of the sub err subroutine’ unless 
ACTION CANT RESTART is specified. If the value ACTION CANT RESTART is specified, 
the sub err subroutine signals the illegal return condition. 
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Handler Operation 


All handlers for the any other condition must either pass the sub error 
condition on to another handler, or else must handle the condition correctly. 
Correct handling consists of printing the error message and of respecting the 
cant restart, default restart, and quiet restart flags, unless the environment 
deliberately countermands these actions (for example, for debugging purposes). 


If an application program wishes to call a subsystem that reports errors by 
the sub err subroutine and wishes to replace the standard system action for 
some classes of sub err subroutine calls, the application should establish a 
handler for the sub error condition by a PL/I on statement. When the handler 
is activated as a result of a call to the sub err subroutine by some dynamic 
descendant, the handler should call the find condition info subroutine to obtain 
the sub.error info ptr that points to the structure deScribed in "Info Structure" 
below. i = 


Info Structure 


The structure pointed to by sub error info ptr is declared as follows in 
the sub error info.inel.pl1 include file: 


del 1 sub error info aligned based, 
2 header = aligned like condition info header, 
2 retval fixed bin(35), = aa 
2 name ehar(32), 
2 info ptr ptr; 
where: 


1. header 
is a standard header required at the beginning of each information 
structure provided to an on unit. See "Information Header Format" 
in the MPM Reference Guide for further details. 


2. retval 
is the return value. The standard environment sets this value to 
zero. 


3. $name 
is the name of the module encountering the condition. 


4, info ptr 
= is a pointer to additional information associated with the condition. 
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The handler should check sub err info.name and sub err info.code to make 
sure that this particular call to the sub err’ subroutine is the one desired 
and, if not, call the continue to signal subroutine. If the handler determines 
that it wishes to intercept this case of the sub error condition, the information 
structure provides the message as converted, switches, etc. If control returns 
to the sub err subroutine, any change made to the value of info.retval is 
returned to the caller of this subroutine. 
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Name: suffixed_name_ 


“This subroutine handles storage system entrynames. It provides an entry 
point that creates a properly suffixed name from a user-supplied name that might 
or might not include a suffix, an entry point that changes the suffix on a 
user-supplied name that might or might not include the original suffix, and an 
entry point that finds a segment, a directory, or a multisegment file whose name 
matches a user-supplied name that might or might not include a suffix. It is 
intended to be used by commands that deal with segments with a standard suffix, 
but that do not require the user to supply the suffix in the command arguments. 


Entry: suffixed_name_$find 


This entry point attempts to find a directory entry whose name matches a 
user-supplied name that might or might not include a_ suffix. This directory 
entry can be a segment, directory, or a multisegment file. 


Usage 


declare suffixed_name_ $find entry (char(*), char(*), char(*), char(32), 
fixed bin(2), fixed bin(5), fixed bin(35)); 


call suffixed_name $find (directory, name, suffix, entry, type, mode, 


code); 
where: 
1. directory (Input) 
is the name of the directory in which the entry is to be found. 
2. name (Input) 
is the name that has been supplied by the user, and that might or 
might not include a suffix. 
3. suf fix (Input) 
is the suffix that is supposed to be part of name. It should not 
contain a leading period. 
4, entry (Output) | 
is a version of name that includes a suffix. It is returned even if 
the directory entry, directory>entry, does not exist. 
‘5. type (Output) 


is a switch indicating the type of directory entry that was found. 


0 no entry was found 

1 a segment was found 

2 a directory was found 

3 a multisegment file was found 
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Entry 


Usage 


where 


1. 


2. 


mode 


code 


(Output) 
is the caller's access mode to the directory entry that was found. 
See the hes $append branch entry point in the MPM Subroutines for a 
description of mode. The the caller's access mode to the 
multisegment file directory is returned for a multisegment file. 


(Output) 

is a standard’status code. It may be one of the following: 

error table $noentry 
no directory entry that matches name was found 

error table $no info . 
No directory entry that matches name was found, and 
furthermore, the caller does not have status permission to the 
directory 


error table $incorrect_ access 


a directory entry that matches name was found, but the caller 
has null access to this entry, and to the directory containing 
this entry 

error table $entlong 
the properly suffixed name that was made is longer than name 


: suffixed name_$make 


This entry point makes a properly suffixed name out of a name supplied by 
the user that might or might not include a suffix. 


declare suffixed_name_$make entry (char(*), char(*), char(32), 
fixed bin(35)); 


call suffixed_name_$make (name, suffix, proper name, code); 


name 


suffix 


proper_ 


code 


(Input) 
is as above. 


(Input) 
is as above. 


name (Out put) 
is the suffixed version of name. 


(Out put ) 
is a standard status code. It may be one of the following: 
error _ table $entlong 
the properly suffixed name that was made is longer’ than 
proper name; proper_name contains only a part of the properly 
suffixed name 
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Entry: suffixed_name_$new_suffix 


This entry point creates a name with a new suffix by changing the (possibly 
existing) suffix on a uSer-Supplied name to the new suffix. If there is no 
suffix on the user-supplied name, then the new suffix is merely appended to the 
user-Supplied name. 


Usage 


declare suffixed_name $new suffix entry (char(*), char(*), char(*), 
ehar(32), fixed bin(35)); 


call suffixed_name $new_suffix (name, suffix, new_suffix, new_name, code); 


where: 
ne name (Input) 
is as above. , 
2. suffix (Input) 
is the suffix that might or might not already be on name. 
3% new_ suffix (Input) 
is the new suffix. 
th, new _name (Output) 
is the name that was created. If name ends with .suffix, then 
-new_ suffix replaces .suffix in new_name. Otherwise, new_name is 
formed by appending .new_suffix to name. 
5. code (Output) 
is a standard status code. It may be one of the following: 
error table $entlong 
meaning that the suffixed new name is longer than new_name and 
therefore new_name contains only part of the suffixed new name 
Note 


If error_table $no_s permission is encountered during the processing for 
suffixed_name_$find, it 1s ignored and is not returned in the status code. 
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Name: sus signal _handler_ 


The sus signal handler’ subroutine is for use as the static condition handler 
for the sus condition. The standard process overseers establish this handler 
by calling sct manager $set. For interactive processes, the sus condition 
typically occurs when the process is disconnected from its login terminal channel. 
For absentee processes, the sus_ condition occurs when the operators suspend the 
job. 


When the user reconnects to the process, sus signal handler_ may attempt to 
execute an exec com, according to whether reconnect ec enable or 
reconnect ec disable was last called before disconnection. a 


Entry: sus Signal handler $reconnect ec enable 


This entry point enables searching for the segment reconnect.ec when the 
user reconnects to a disconnected process. As a result, sus signal handler 
looks first in the user's home directory, then in his project directory 
(>user dir dir>Project name), and finally in >system control dir. When the 
reconnect.éc segment is found, the command "exec com >Directory name>reconnect" 
is executed. = 


Usage 


declare sus Signal handler _$reconnect_ec enable entry; 


call sus signal handler $reconnect_ec enable (); 


' Notes 


The use of reconnect.ec is enabled automatically by the standard process 
overseer process overseer . 


Invocation of the reconnect.ec iS not automatically enabled by the 
project start up process overseer. Thus, when using project start up , the project 
administrator may enable the invocation of reconnect.ec at any point in the 
project start up.ec by using the reconnect ec enable command (See MPM Commands). 


The current command processor is used to execute the reconnect.ec command. 
If the user is using the abbrev command processor, any applicable abbreviation 
will be expanded. 
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Entry: sus signal handler $reconnect ec disable 


This — entry point reverses the effect of the 
sus Signal handler $reconnect ec enable entry. After reconnection to a 
disconnected process, there is no attempt made to find or invoke the exec com 
"reconnect.ec". . 


‘Usage 


declare sus signal handler _$reconnect ec disable entry; 


call Sus Signal handler $reconnect ec disable Cys 
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Name: system_info_ 


The system info — subroutine allows the user to obtain information 
concerning system parameters. All entry points that accept more than one 
argument count their arguments and only return values for the number of 
arguments given. Certain arguments, such as the price arrays, must’ be 
dimensioned as shown. 


Entry: system_info_ $installation_id 


This entry point returns the 32-character installation identifier that is 
typed in the header of the how_many_users command (described in the MPM i 
Commands) when the -long control argument is specified. 


Usage 


declare system_info_ $installation id entry (char(*)); 


call system_info $installation_id (id); 


where id (Output) is the installation identifier. 


Entry: system_info_$sysid 


This entry point returns the eight-character system identifier that is 
typed in tne header of the who command and at dial-up time. 


¢ 


Usage 


declare system_info $sysid entry (char(*)); 


call system_info $sysid (sys); 


where sys (Output) is the system identifier that identifies the current version 
of the system. 


This entry point returns several character strings that more formally 
identify the installation. 
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Usage 


declare system_info $titles entry (char(*), char(*), char(*), char(*)); 


call system_info $titles (c, d, cc, dd); 


where: 
‘te e (Out put ) 

is the company or institution name (a maximum of 64 characters). 
2. d (Out put) 

is the department or division name (a maximum of 64 characters). 
3. ee (Output) 

is the company name, double spaced (a maximum of 120 characters). 
ye. dd (Out put ) 


is the department name, double spaced (a maximum of 120 characters). 


Entry: system_info_ $users 


This entry point returns the current and maximum number of load units and 
users. 


Usage 


declare system_info $users entry (fixed bin, fixed bin, fixed bin, 
fixed bin); 


call system_info $users (mn, nn, mu, nu); 


where: 
1. mn (Out put) 
is the maximum number of users. 
2. nn (Out put) 
is the current number of users. 
3 mu (Out put) 
is the maximum number of load units (times 10). 
4, nu (Output) 


is the current number of load units (times 10). 
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Entry: system_info $timeup 


This entry point returns the time at which the system was last started up. 
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Usage 


declare system_info_ $timeup entry (fixed bin(71)); 


call system_info_$timeup (tu); 


where tu (Output) is when the system came up. 


Entry: system_info_$next_shutdown 


This entry point returns the time of the next scheduled shutdown, the 
reason for the shutdown, and the time when the system will return, if these data 
are available. 


Usage 


declare system _info_$next_ shutdown entry (fixed bin(71), char(*), 
fixed bin(71)); 


call system_info_$next_shutdown (td, rsn, tn); 


where: 

he td (Output) 
is the time of the next scneduled shutdown. If none is scheduled, 
this is 0. 

2. rsn (Output). 
is the reason for the. next shutdown (a maximum of 32 characters). 
If it is not known, it is blank. 

3. tn (Output) 


is the time the system will return. If it is not known, it is 0. 


Entry: system_info_$prices 


This entry point returns the per-shift prices for interactive uSe. 
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Usage 


where 


Entry 


Usage 


where 


Ly 


2. 


12/79 


declare system_info $prices entry ((0:7) float bin, (0:7) float bin, 
float bin, (0:7) float bin, float bin, float bin); 


call system_info $prices (cpu, log, pre, cor, dsk, reg); 


cpu 


log 


pre 


cor 


dsk 


reg 


This entry point returns the per-shift prices for system device usage. 


declare system info $device prices entry (fixed bin, ptr); 


is 


is 


is 


is 


is 


is 


the 


the 


the 


the 


the 


the 


(Output) 
CPU-hour rate per shift. 


(Output) 
connect-hour rate per shift. 


(Output) 
process-hour rate per shift. 


(Output) 
page-second rate for main memory per shift. 


(Output) 
page-second rate for secondary storage. 


(Output) 
registration fee per user per month. 


system info $device prices 


call system_info $device prices (ndev, dev ptr); 


ndev 


dev_ptr 


(Output) 


is the number of devices with prices. 


points to an array where device prices are stored. 


(Input) 
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Note 


system_info_ 


In the above entry point, the user must provide the following array (in his 


storage) for device prices: 


del 1 dvt(16) based (dev _ptr) aligned, 
2 device id char (8), 
2 device price (0:7) float bin; 
where: 
1 dvt 


is the user structure. Only the first ndev of the 16 is filled in. 


as device id 
is the name of the device. 


3. device price 
is the per-hour price for the device. 


@ 


Entry: system_info $resource price 


This entry point returns the price of a specified resource. 


Usage 


declare system _ info $resource price entry (char(*), float bin, 
fixed bin (35)); 


call system_info $resource price entry (name, price, code); 


where: 
1. name © (Input) 
is the name of the resource. 
2. price (Output) 
is the price of the resource in dollars per unit. 
33 code (Output) 


is a standard status code. It will be error_table $noentry if the 


resource is not in the price list. 
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Entry: system_info $abs _chn 


This entry point returns the event channel and process ID for the process 
that is running the absentee user manager. 


Usage 


declare system_info_$abs_chn entry (fixed bin(71), bit(36) aligned); 


call system_info_$abs_chn (ec, p_id); 


where: 

1. ec (Output) 
is the event channel over which signals to absentee_user_manager_ 
should be sent. ; 

ee p_id (Output) 


is the process ID of the absentee manager process (currently the 
initializer). 
Entry: system_info $rs_name 


This entry point returns the rate structure name corresponding to a rate 
structure number. 


Usage 


declare system_info_$rs name entry (fixed bin(17), char(*), fixed bin(35)); 


call system_info_$rs_name (rs _number, rs_name, code); 


where: 

1. rs_number (Input) 
is the number of a rate structure. 

eae rs_name (Output) 
is the name corresponding to rs_number. (The name can be up to 32 
characters long.) 

3. code (Output) 


is zero if no error occurred, or error_table $no_ entry if rs_number 
is not the number of a defined rate structure. 
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Entry: system_info_$rs_number 


This entry point returns the rate structure number corresponding to a rate 
structure name. 


Usage 


declare system_info_ $rs_number entry (char(*), fixed bin(17), 
fixed bin(35)); 


call system_info_$rs_ number (rs_name, rs_ number, code); 


where: 
1. rs_name (Input) 
is the name of a rate structure. 
2. rs number (Output) 
is the number corresponding to rs_name. 
3 code (Output) 


is zero if no error occurred, or error_table $no_entry if rs_ name is 
not the name of a rate structure. 
Entry: system_info_$max_rs_ number 


This entry point returns the largest valid rate structure number. 


Usage 


declare system_info_ $max_rs_ number entry (fixed bin(17); 


call system_info_$max_rs_number (rs_ number); 


where: 


Ts. rs_ number (Output) 
is the largest valid rate structure number. If it is zero, there 
are no rate structures defined, other than the default one in 
installation parms. 
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Entry: system_info $default_absentee queue 


This entry point returns the number of the default absentee queue used for 
submission of absentee jobs by the enter_abs request, pli_abs, fortran _abs, 
etc., commands. 
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Usage 


declare system_info_ $default_absentee queue entry (fixed bin); 


call system_info_$default absentee queue (default_q); 


where: 


1. default _q (Output) 
is the default absentee queue. 


Entry: system_info_$next_shift_ change 


This entry point returns the number of the current shift, the time it 
started, the time it will end, and the number of the next shift. 


Usage 
declare system_info_ $next_ shift change entry (fixed bin, fixed bin(71), 
fixed bin, fixed bin(71); 


call system_info_ $next_shift_change (now_shift, change time, new_shift, 
start_time); 


where: 
sg now shift (Output) 

is the current shift number. 
2% change time (Output) 

is the time the shift changes. 
3. new shift (Output) 

is the shift after change time. 
4, start_time (Output) 


is the time the current shift started. 


Entry: system_info $shift_table 


This entry point returns the local shift definition table of the system. 
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Usage 


declare system_info_$shift_table entry ((336) fixed bin); 


call system_info $shift_table (stt); 


where stt (Output) isa table of shifts, indexed by half-hour within the week 
e.g., stt(1) gives the shift for 0000-0030 Mondays. 


Entry: System_info_ $abs_prices 


This entry point returns the prices for CPU and real time for each absentee 
queue. 


Usage 


declare system_info $abs prices entry ((4) float bin, (4) float bin); 


call system_info_$abs_ prices (cpurate, realrate); 


where: 
Te epurate (Output) 

is the price per CPU hour for absentee queues 7 to 4. 
an realrate (Output) 


is the memory unit rate for absentee queues 1 to 4. 


Entry: system_info_$io_ prices 


This entry point returns the prices for unit processing for each I/O daemon 
queue. 


Usage 


declare system_info $io_ prices entry ((4) float bin); 


call system_info_$io_prices Crp) 


where rp (Output) is the price per 1000 lines for each I/O daemon queue. 
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Entry: system_info_ $last_shutdown 


This entry point returns the clock time of the last shutdown or crash and 
an eight-character string giving the ERF (error report form) number of the last 
crash (blank if the last shutdown was not a crash). 


Usage 


declare system info $last_shutdown entry (fixed bin(71), char(*)); 


call system_info $last_shutdown (time, erfno); 


where: 
1. time (Output) 

is the clock time of the last Shutdown. 
2. erfno (Output) 


is the ERF number of the last crash, or blank. 


Entry: system_info_$access ceiling 


This entry point returns the system high access authorization or class. 


Usage 


declare system_info $access ceiling entry (bit(72) aligned); 


call system_info_$access ceiling (ceil); 


where ceil (Output) is the access ceiling. 


Entry: system_info_$level_names 


This entry point returns the 32-character long names and eight-character 
short names for sensitivity levels. 


Usage 
declare system_info $level_names entry (dim(0:7) char(32), dim(0:7) 
char(8)); 


call system_info_$level_names (long, short); 
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where: 
1.” long (Output) 

is an array of the long level names. 
2. short (Out put) 


is an array cf the short level names. 
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Entry: system_info $category names 


This entry point returns’ the 32~character long names and the 
eight-chsracter short names for the access categories. 


Usage 


declare system_info $category names entry (dim(18) char(32), dim(18) char(8)); 


eall system_info $category names 
(long, short); 


where the arguments are the same as for the system_info_$level_names entry 
point. 
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Entry: system_info_$ARPANET host_number 


This entry point returns the Advanced Research Projects Agency Network 
{ARPANET) address of the installation. If the installation is not attached to 
the ARPANET, the value ~1 is returned. 


Usage 


declare system_info $ARPANET_ host_number entry (fixed bin(16)); 


call system_info_$ARPANET_ host _number (host_num); 


where host_num (Output) is the ARPANET host address. 
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Name: terminate _process_ 


This procedure causes the process in which it is called to be terminated. 
The arguments determine the exact nature of the termination. 


Usage 


declare terminate process entry (char(*), ptr); 


call terminate process (action, info ptr); 


where: 

ies action (Input) 
specifies one of four general actions to be taken upon process 
termination. The permissible values are logout, new proc, 
fatal_error, or init_error (see "Notes"). - 

2 info_ptr (Input) 
points to more specific information about the action to be taken at 
termination. The structure pointed to by info_ptr depends upon 
action (see "Notes"). 

Notes 


If action is logout then the user's process is logged out. The info ptr 
points to: = 


del 1 logout_info aligned, 


2 version fixed bin, 
2 hold bit(1) unaligned, 
2 brief bit(1) unaligned, 
2 pad bit(34) unaligned, 
where: 
1. version 
must be 0. 
2. hold 
must be "1"b if the terminal associated with this process is not to 
be hung up, so that another user may log in. 
35 brief 
must be "1"b if the logout message is to be suppressed. 
4, pad 


must be "0O"b, 
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If action is new_proc, then the user's current process is logged out and a 
new process is created. The info ptr points to: 


del 1 new_proc_ info aligned, 
2 version fixed bin, 
2 authorization option bit(1) unaligned, 
2 pad bit(35) unaligned, 
2 new_authorization bit(72) aligned; 
where: 
Wa version 


must be 1. 


2. authorization option 
must be 1 if new_authorization is to be used. 


3. pad 
must be OQ. 


4, new_authorization 
is the authorization of the new process. 


If action is fatal _error, then the user's current process is terminated due 
to an unrecoverable error. A fatal error message is printed on the terminal and 
a new process is created. The info ptr points to: 


del 1 fatal _error_ info aligned, 
2 version fixed bin,,. 
2 status_code fixed bin(35); 
where: 
1. version 
must be 0. 
ae status code 


is an error_table code indicating the nature of the fatal error, the 
corresponding error message will be printed on the user's console. 


If action is init _error, then the user's process is logged out anda 
message indicating that his process could not be initialized is printed. The 
info ptr points to: 


del 1 init_error_info aligned, 
2 version fixed bin, 
2 status code fixed bin(35); 
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where: 
1. version 

must be 0Q. 
can status code 


is a standard Multics code indicating the nature of the error. 


See the MPM Commands for a description of the logout and new proc commands. 
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Name: timer_manager_ 


The timer manager subroutine allows many CPU usage timers and real-time 
timers to be used simultaneously by a process. The caller can specify for each 
timer whether a wakeup is to be issued or a specified procedure is to be called 
when the timer goes off. 


The timer_manager_ subroutine fulfills a specialized need of certain 
sophisticated ~ programs. A user should be familiar with interprocess 
communication in Multics and the pitfalls of writing programs that can run 
asynchronously within a process. For example, if a program does”) run 
asynchronously within a process and it does input or output with the tty_ I/0 
module, then the program should issue the "start" control order of tty _ before 
it returns. This is necessary because a wakeup from tty_ may be intercepted by | 
the asynchronous program. Most pitfalis can be avoided by using only the 
timer_manager $sleep entry point. 


For most uses of the timer manager Subroutine, a cleanup condition 
handler, which resets all the timers that might be set by a software subsystem, 
should be set up. If the subsystem is aborted and released, any timers set up 
by the subsystem can be reset instead of going off at undesired times. 


To be used, the timer_manager_ subroutine must be established as the 
condition handler for the alrm and cput conditions. This is done automatically 
by the standard Multics environment. 


Generic Arguments 


At least one of the following arguments is called in all of the 
timer_manager_ entry points. For convenience, these common arguments are 
described below rather than in each entry point description. 


¥s channel 
is the name of the event channel (fixed binary(71)) over which a 
wakeup is desired. Two or more timers can be running 
simultaneously, all of which may, if desired, issue a wakeup on the 
same event channel. 


2e routine 
is a procedure entry point that is called when the timer goes off. 
The entry value must be valid when the routine is invoked, i.e., if 
the routine is an internal procedure, the proceudre that created the 
entry value must still be on the stack. The routine is called as 
follows: 


declare routine entry (ptr, char(*)); 


call routine (mc_ptr, name); 
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where: . 

me ptr (Input) 
is a pointer to a structure containing the machine 
conditions at the time of the process interrupt. 

name (Input) 


is the condition name: alrm for a real-time timer and 
eput for a CPU timer. 


(See the signal subroutine for a full description of the me ptr and 
name arguments.) Two or more timers can be running simultaneously, 
all of which may, if desired, call the same routine. 


Before the routine is called, a condition wall is established. The 
wall is established with the following statement: 


on any other system; 


See the MPM Reference Guide and the Multics PL/1 Reference Manual 
(AM&83) for more information. Any conditions signalled in the routine 
are handled by default error handler if the routine does not handle 
them. They are not handled by user condition handlers on the stack 
above the call to the routine. 
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3. time 
is the time (fixed binary(71)) at which the wakeup or call is 
desired. 


4, flags ; 
is a 2-bit string (bit(2)) that determines how time is to be 
interpreted. The high-order bit indicates whether it is an absolute 
or a relative’ time. The low-order bit indicates whether it is in 
units of seconds or microseconds. Absolute real time is time since 
January 1, 1901, Q000 hours Greenwich mean time, i.e., the time 
returned by the clock subroutine (described in the MPM 
Subroutines). Absolute CPU time is total virtual time used by the 
the process, i.e., the time returned by the cpu time and paging 
subroutine (described in the MPM Subroutines). Relative time begins 
when the timer_manager_ subroutine is called. 


"711"b means relative seconds 
"10"b means relative microseconds 
"071"b means absolute seconds 
"O0"™b means absolute microseconds 


Entry: timer_manager_$sleep 


This entry point causes the process to go blocked for a period of real 
time. Other timers that are active continue to be processed whenever they go 
off; however, this routine does not return until the real time has been passed. 


Usage 


declare timer_manager $sleep entry (fixed bin(71), bit(2)); 


call timer_manager $sleep (time, flags); 


The time is always real time; however, it can be relative or absolute, 
seconds or microseconds, as explained above in "Generic Arguments." 


Entry: timer_manager_$alarm_call 


This entry point sets up a real-time timer that calls the routine specified 
when the timer goes off. 


Usage 


declare timer_manager_$alarm_call entry (fixed bin(71), bit(2), entry); 


call timer_manager_$alarm_call (time, flags, routine); 
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Entry: timer_manager_$alarm_call_ inhibit 


This entry point sets up a real-time timer that calls the handler routine 
specified when the timer goes off. The call is made with all interrupts 
inhibited (i.e., all interprocess’ signal (IPS) are masked off). When the 
handler routine returns, interrupts are reenabled. If the handler routine does 
not return, interrupts are not reenabled and the user process may malfunction. 


Usage 


declare timer_manager_$alarm_call_ inhibit entry (fixed bin(71), bit(2), 
entry); 


call timer_manager_$alarm_call_ inhibit (time, flags, routine); 


Entry: timer_manager_ $alarm_wakeup 


This entry point sets up a real-time timer that issues a wakeup on the 
event channel specified when the timer goes off. The event message passed is 
the string "alarm ",. (See the ipe Subroutine for a discussion of event 
channels.) rede ~ 


Usage 


declare timer_manager_$alarm_wakeup entry (fixed bin(71), bit(2), 
fixed bin(71)); 


call timer_manager_$alarm_wakeup (time, flags, channel); 


Entry: timer_manager_ $cpu_call 


This entry point sets up a CPU timer that calls the routine specified when 
the timer goes off. 


Usage 


declare timer_manager $cpu_call entry (fixed bin(71), bit(2), entry); 


call timer_manager $cpu_call (time, flags, routine); 
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Entry: timer_manager_$cpu_call_inhibit 


This entry point sets up a CPU timer that calls the handler routine 
specified when the timer goes off. The call is made with all interrupts 
inhibited (i.e., all IPS are masked off). When the handler routine returns, 
interrupts are reenabled. If the handler routine does not return, interrupts 
are not reenabled and the user process may maifunction. 


Usage 


declare timer_manager_ $cpu_call_inhibit entry (fixed bin(71), bit(2), 
entry); 


call timer_manager_$cpu_call_inhibit (time, flags, routine); 


Entry: timer_manager_$cpu_wakeup 


This entry point sets up a CPU timer that issues a wakeup on the event 
channel specified when the timer goes off. The event message passed is the 
string "cpu_time". 


Usage 


declare timer manager _$cpu wakeup entry (fixed bin(71), bit(2), 
fixed bin(71)); 


call timer_manager_$cpu_wakeup (time, flags, channel); 
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Entry: timer_manager_$reset_cpu_call 


This entry point turns off all CPU timers that call the routine specified 
when they go off. 


Usage 


declare timer_manager $reset_cpu_call entry (entry); 


call timer_manager_$reset_cpu_call (routine); 
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Entry: timer_manager_$reset_cpu_wakeup 


This entry point turns off all CPU timers that issue a wakeup on the event 
channel specified when they go off. 
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Usage 


declare timer _manager_$reset_cpu_wakeup entry (fixed bin(71)); 


call timer_manager_$reset_cpu wakeup (channel); 


Entry: timer_manager_$reset_alarm_call 


This entry point turns off all real-time timers that call the routine 
Specified when they go off. 


Usage 


declare timer_manager_$reset_alarm_call entry (entry); 


call timer_manager_$reset_alarm_call (routine); 


Entry: timer_manager_$reset_alarm_wakeup 


This entry point turns off all real-time timers that issue a wakeup on the 
event channel specified when they go off. 


Usage 


declare timer_manager_$reset_alarm_wakeup entry (fixed bin(71)); 


call timer_manager_$reset_alarm_wakeup (channel); 
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Name: tssi_ 


The tssi (translator storage system interface) subroutine simplifies the 
way the language translators use the storage system. The tssi $get_segment and 
tssi_$get_file entry points prepare a segment or multisegment file for use as 
output from the translator, creating it if necessary, truncating it, and setting 
the access control list (ACL) to rw for the current user. The 
tssi_$finish_segment and tssi_$finish_file entry points set the bit counts of 
segments or multisegment files, make them unknown, and put the proper ACL on 
them. The tssi_$clean_up_ segment and tssi_$clean_up file entry points are used 
by cleanup procedures in the translator (on segments and multisegment files 
respectively). 


Entry: tssi_$get segment 


This entry point returns a pointer to a specified segment. The ACL on the 
segment is rw for the current user. If an ACL must be replaced to do this, 
aclinfo_ptr is returned pointing to information to be used in resetting the ACL. 


Usage 


declare tssi $get segment entry (char(*), char(*), ptr, ptr, 
fixed bin(35)); 


call tssi_$get_segment (dir_name, entryname, seg ptr, aclinfo_ptr, code); 


where: 
1s dir_name (Input) 
is the pathname of the containing directory. 
25 entryname (Input) 
is the entryname of the segment. 
3. seg ptr (Out put ) 
is a pointer to the segment, or is null if an error is encountered. 
4, aclinfo_ptr (Out put ) 
is a pointer to ACL information (if any) needed by the 
tssi_$finish_segment entry point. 
pa code (Out put ) 


is a storage system status code. 


7-207 AK92 


tssi . tssi 


Entry: tssi_$get file 


This entry point is the multisegment file version of the tssi $get_ segment 
entry point. It returns a pointer to the specified file. Additional components, 
if necessary, can be accessed using the msf manager ¢$get ptr entry point (see 
the description of the msf manager subroutine in this document), with the original 
segment considered as component 0. 


Usage 


declare tssi $get file entry (char(*), char(*), ptr, ptr, ptr, 
fixed bin(35)); 


call tssi_ $get file (dir name, entryname, seg ptr, aclinfo ptr, feb ptr, 


code); 
where: 
1s dir name (Input) 
~ is the pathname of the containing directory. 
2. entryname (Input) 
is the entryname of the multisegment file. 
3. seg ptr (Output) 
~ is a pointer to component 0 of the file. 
4, aclinfo _ptr (Output) 
1S a pointer to ACL information (if any) needed by the tssi _$finish_ file 
entry point. 
5. feb ptr (Output) 
is a pointer to the file control block needed By the msf_ manager _ 
subroutine. 
6. code (Output) 


is a storage system status code. 


Entry: tssi_ $finish_ segment 


This entry point sets the bit count on the segment after the translator is 
finished with it. It also terminates the segment. If the segment existed before 
the call to tssi_$get_segment, the ACL is reset to the way it was before the 
tssi_ $get_ segment entry point was called. If no ACL existed for the current 
user, the mode is set to "mode" for the current user. If the segment was 
created, and the "mode" parameter contains the "“e" mode, all entries on the 
segment's ACL (as derived from the containing directory's Initial ACL) receive 
the "e" bit, as well as the other modes specified. The current user, if not 
specified on the Initial ACL, receives an ACL term of "mode" on the segment. 
Otherwise, the segment's Initial ACL is restored, and, if the current user does 
not have an ACL term, the segment receives an ACL term of "mode" for the user. 
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Usage 


declare tssi_$finish_segment entry (ptr, fixed bin(24), bit(36) aligned, 
ptr, fixed bin(35)); 


call tssi_$finish_segment (seg ptr, be, mode, aclinfo_ptr, code); 


where: 

i seg ptr (Input) 

is a pointer to the segment. 

2. be (Input) 
is the bit count of the segment. 

3. mode (Input) 
is the access mode to be put on the segment. 
"170"b re access 
WIG 1b rw access 

4. aclinfo_ptr (Input) 
is a pointer to the saved ACL information returned by the 
tssi_$get_segment entry point. 

ae code (Out put) 


is a storage system status code. 


Entry: tssi_$finish_file 


This entry point is the same as the tssi_$finish_segment entry point, 
except that it works on multisegment files, and closes the file, freeing the 
file control block. 


Usage 


declare tssi_$finish_ file entry (ptr, fixed bin, fixed bin(24), bit(36) 
aligned, ptr, fixed bin(35)); 


call tssi_$finish_file (fcb_ptr, component, be, mode, aclinfo_ptr, code); 


where: 

As feb_ptr (Input) 
LS: -a pointer to the file control block returned by the 
tssi_$get_file entry point. 

2s component (Input) 
is the highest-numbered component in the file. 

3. be (Input) 


is the bit count of the highest-numbered component. 
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mode (Input) 
is the access mode to be put on the multisegment file. 
aclinfo ptr. (Input) 
is a pointer to the saved ACL information returned by the 


tssi_$get_file entry point. 


code (Output) 
is a storage system status code. 
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Entry: tssi_$clean_up_ segment 


Programs that use the tssi_ subroutine must establish a cleanup procedure 
that calls this entry point. (For a discussion of cleanup procedures see 
"Nonlocal Transfers and Cleanup Procedures" in Section VI of the MPM Reference 
Guide.) If more than one call is made to the tssi_ $get_ segment entry point, the 
cleanup procedure must make the appropriate call to the tssi ¢clean up segment 
entry point for each aclinfo ptr. ~ = e= 


The purpose of this call is to free the storage that the tssi_$get_segment 
entry point allocated to save the old ACLs of the segments being translated. It 
is to be used in case the translation is aborted (e.g., by a quit signal). 


Usage 


declare tssi_$clean_up_ segment entry (ptr); 


call tssi_$clean_up_segment (aclinfo ptr); 


where aclinfo_ptr (Input) is a pointer to the saved ACL information returned by 
the tssi_$get_ segment entry point. 


Entry: tssi_$clean_up file 


This entry point is the cleanup entry point for multisegment files. In 
addition to freeing ACLs, it closes the file, freeing the file control block. 


Usage 


declare tssi_$clean_up_file entry (ptr, ptr); 


call tssi_$clean_up_file (feb_ptr, aclinfo ptr); 


where: 

Ts feb_ptr (Input) 
is a pointer to the file control block returned by the 
tssi_$get_file entry point. 

oy aclinfo_ptr (Input) 


is a pointer to the saved ACL information returned by the 
tssi_$get_segment entry point. 
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Name: unwinder 


The unwinder subroutine is used to perform a nonlocal goto on the Multics 
stack. It is not intended to be called by direct programming (i.e., an explicit 
call statement in a program) but rather, by the generated code of a translator. 
For example, it is automatically invoked by a PL/I goto statement involving a 
nonlocal label variable. 


When invoked, the unwinder Subroutine traces the Multics stack backward 
until it finds the stack frame associated with its label variable argument or 
until the stack is exhausted. In each stack frame it passes, it invokes the 
handler (if any) for the cleanup condition. When it finds the desired stack 
frame, it passes control to the procedure associated with that frame at the 
location indicated by the label variable argument. If the desired stack frame 
cannot be found or if other obscure error conditions arise (e.g., the stack is 
not threaded correctly), the unwinder Subroutine signals the unwinder error 
condition. If the target is not on the current stack, and there is a stacK in a 
higher ring, that stack is searched after the current one is unwound. 


Usage 


declare unwinder_ entry (label); 


call unwinder_ (tag); 


where tag (Input) is a nonlocal label variable. 
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Name: valid _decimal_ 


The valid decimal_ function tests decimal data for validity. 


Usage 


declare valid decimal_ entry (fixed bin, ptr, fixed bin) returns (bit(1)); 


b = valid decimal  (dtype, dptr, dprec); 


where: 

1. dtype (Input ) 
is the data type descriptor of the decimal data. It must be one of 
the following: 9-12, 29:30, 35-36, 38-39, 41-46. 

2. dptr (Input) 
is a pointer to the data to be tested for validity. 

3. dprec (Input) 
is the precision of the data. 

igs b (Output) 
is the value returned by valid decimal . It is "1"b if the data is 
valid, "O"b otherwise. 

Notes 


For decimal data to be valid, it must pass the following tests: (1) The 
precision must be > 0 and <= 59; (2) The data type descriptor must be one 


handled by valid _decimal_; (3) If the data is stored as nonoverpunched 9-bit 
characters, then if it has a sign, then the sign must be either "+" or "-", The 
digits must all be one of the ASCII characters "0123456789"; (4) If the data is 


Stored as overpunched 9-bit characters, then the sign character must be either 
octal 173, i175, or in the range 101 to 122. The remaining digits must all be 
one of the ASCII characters "0123456789"; (5) If the data is stored as 4-bit 
characters, then if it has a sign, then sign must be in the range "1010"b to 
"1111"b. <All digits must be in the range "0000"b to "1001"b. 
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Name: write allowed_ 


The write allowed function determines whether a subject of specified 
authorization has access (with respect to the access isolation mechanism) to 
write an object of specified access class. For information on access classes, 
see "Nondiscretionary Access Control" in Section 6 of the MPM Reference Guide. 


Usage 


declare write allowed entry (bit(72) aligned, bit(72) aligned) returns 
(bit(1) aligned); 


returned bit = write_allowed_ (authorization, access class); 


where: 
a authorization (Input) 

is the authorization of the subject. 
2. access class (Input) 

is the access class of the object. 
oo returned bit (Output) 


indicates whether the subject is allowed to write the object. 
a ead @ write is allowed 
OND write is not allowed 
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DATA BASE DESCRIPTIONS 


This section contains descriptions of some Multics data bases presented in 
alphabetical order. Each description contains the name of the data base, 
discusses its purpose, and shows the correct usage. 


Name 


The "Name" heading shows the acceptable name by which the data base is 
referenced. The name is usually followed by a discussion of the purpose and 
function of the data base and the results that may be expected from referencing 
agi oes 


This part of the data base description contains a declaration of the data 
base and its structure. 
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Name: sys_info 

The sys_info data base is a wired-down, per-system data base. It is 
accessible in all rings but can be modified only in ring Q. It contains many 
system parameters and constants. All references to it are made through 


externally defined variables. 


Usage 
del sys_info$clock_ bit(3) aligned external static; 
del 1 sys_info$ips_mask data aligned external static, 
2 count ~ fixed binary, 
2 masks (sys infog$ips mask data.count), 
3 name a = ae echar(32) aligned, 
3 mask bit(35)aligned; 
del sys info$page size fixed binary(19) external static; 
del sys _info$max seg size fixed binary(19) external static; 
del sys info$default stack length fixed binary(19) external static; 
del sys info$default max length fixed binary(19) external static; 
del sys infog$access class ceiling bit(72) aligned external static; 
del sys info$time correction constant fixed binary(71) external static; 
del sys info$time delta -. fixed binary(35) external static; 
del sys_info$maxlinks fixed binary external static; 
del sys info$time of bootload fixed binary(71) external static; 
del sys_info$time zone echar(3) aligned external static; 
where: 
Ie. Lock 


~ is the 


2. ips mask data 
is the 
signal 


array that 
(IPS) masks. 


3. count 
is the current number of valid 
4. name 
is the name used to signal the 
mask 
is the IPS mask 
on, 


for the 


6. page size 
is the page size in words. 


7. max seg size 


specifies the number and 


corresponding name. 
and the rest of the bits are off. 


port number of the system controller containing the clock. 


mapping of interprocess 


IPS names. 


IPS condition. 


The mask has one bit 


is the maximum segment size in words. 


default stack length 


Is the default stack maximum size in words. 


9. default max length 


is the default maximum length of segments in words. 
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13. 


14. 


15. 


access class ceiling 
is the maximum access class. 


time correction constant 
is the correction from Greenwich mean time (GMT) in microseconds. 


time delta 


is the same as time correction constant, only in single precision. 
maxlinks 
is the maximum depth to which the system chases a link without 
finding a branch. 


time _of bootload 
1s the clock reading at the time of bootload. 


time zone 
is the name of the time zone (e.g., EST). 
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Name: time table $zones 


This data base is a table that defines the list of time zones accepted by 


the convert date to binary , decode clock value , and encode clock value 
subroutines (all described “in the MPM Subroutines). The table Structure is 
defined the system include file, in time zones .inecl.pli. Time zones may be 


referenced using either uppercase or lowercase abbreviated zone names. The following 
is a list of abbreviations given in the system-supplied table. A site may 
modify this table to define other appropriate time zone abbreviations. 


- GMT Greenwich mean time, zone east of the prime meridian (0 longitude), 
which runs through Greenwich, England, UK. 
EST Eastern Standard Time, 5 hours before GMT, including the eastern US. 
EDT Eastern Daylight Time, applies daylight savings to EST zone, giving 
time 4 hours before GMT. 
CST Central Standard Time, 6 hours before GMT, including the mid-western 
US. 
CDT. Central Daylight Time, applies daylight savings to CST zone, giving 
time 5 hours before GMT. 
MST Mountain Standard Time, 7 hours before GMT, including the Rocky Mountain 
States of the US. 
MDT Mountain Daylight Time, applies daylight savings to MST zone, giving 
time 6 hours before GMT. 
PST Pacific Standard Time, & hours before GMT, including the west coastal 
; States of the US. 
PDT Pacific Daylight Time, applies daylight savings to PST zone, giving 
time 7 hours before GMT. 
AST Atlantic Standard Time, 4 hours before GMT, including Carribean Islands. 
ADT Atlantic Daylight Time, applies daylight savings to AST zone, giving 
time 3 hours before GMT. 
BST British Summer Time, applies daylight Savings to GMT zone, giving time 
1 hour after GMT. 
FWT French Winter Time, 1 hour after GMT, including Western Europe. 
FST French Summer Time, applies daylight savings to FWT zone, giving time 
2 hours after GMT. 
HFH Heure Francais D'Hiver, the French representation of French Winter 
Time (FWT), giving time 1 hour after GMT. 
HFE Heure Francais D'tEte, the French representation of French Summer Time 
_ (FST), giving time 2 hours after GMT. 


Z Universal Time, an alternate name for GMT. 
Usage 
del 1 time zones aligned based (addr (time table $zones)), 
2 version fixed bin, 
2 number fixed bin, 
2 values (0 refer (time zones.number)), 
3 zone char(3) aligned, 
3 pad fixed bin, 


3 zone offset fixed bin(71); 
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time table $zones 7 time table $zones 


where: 
1. time zones 

™ ds the structure located in time table $zones. 
2. version 


is the version number of this structure (currently version!1). 


3% number 
is the number of time zones in the table. 


4, zone 
is the abbreviated time zone character string in uppercase or lowercase. 

Bs pad 

, must be set to zero. 
6. zone offset | . 
~ is the offset, in microseconds, which must be added to convert a 

time expressed in this time zone to a time expressed in the GMT 
zone. 
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APPENDIX A 


APPROVED CONTROL ARGUMENTS 


Appendix A, “Approved Control Arguments", has been deleted since the * 
information is available in the Standards System Designers' Notebook, Order No. 
AN82. 
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APPENDIX B 


SYMBOL TABLE ORGANIZATION 


The information in this section is subject to change. Future Multics 
releases may use a different format of runtime symbol information. 


The free-format area can contain any information whatsoever, and the object 
segment will execute properly. However, the Multics debugging utilities (e.g., 
probe) place stringent requirements on the format of the free area, and these 
are followed by the translators for PL/I, FORTRAN and COBOL. 


The free-format area begins with a fixed-format header, called the 
pl1 symbol block. Despite the name, this block is present even in FORTRAN and 
COBOL-produced object segments. The pl1_symbol_ block gives the options used in 
compiling the segment, and the offsets of the statement map, the root block 
node, and the profile information. 


The remainder of the free-format area consists of the statement map, the 
symbol tree, and the profile information, which are discussed below. 


The PL/I Symbol Block 


The PL/I symbol Diock has the following format (declared in 
pl1_symbol_block.inel.pl1): 


declare 1 pl1_symbol_block aligned, 

2 version fixed binary, 

2 identifier char (8), 

2 flags, 
3 profile bit(1) unaligned, 
3 table bit(1) unaligned, 
3 map bit(1) unaligned, 
3 flow bit(1) unaligned, 
3 io bit(1) unaligned, 
3 table removed bit(1) unaligned, 
3 long profile bit(1) unaligned, 
3 pad bit(29) unaligned, 

2 greatest_severity fixed binary, 

2 root bit(18) unaligned, 

2 profile bit(18) unaligned, 

2 map, 
3 first bit(18) unaligned, 
3 last bit(18) unaligned, 

2 segname, 
3 offset bit(18) unaligned, 
3 length bit(18) unaligned; 
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where: 


11. 


12. 


13. 
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version 
is the version number of the structure. For this version the 
version number is i. 


identifier 
is the constant "pliinfo". 


profile 
is "1"b if the object program contains an execution profile table. 
This table is generated if the -profile control argument is 
specified when the source program is compiled. 


table 
is "1"b if the object program contains a runtime symbol table. A 
runtime symbol table is generated if the -tabie control argument is 
specified when the source program is compiled or if the runtime 
table is required by PL/I put data or get data or FORTRAN namelist 
input/output statements in the source program (see "The PL/I Runtime 
Symbol Table" below). 


map 
is "1"b if the object segment contains a statement map that gives 
the correspondence between source line numbers and locations in the 
object segment (see "The Statement Map" below). The statement map 
is present if the -brief_ table, -profile, or -table control 
arguments are specified when the source program is compiled. 


flow 
is "1"b if the object program contains additional instructions for 
monitoring program flow. This facility is not yet available. 


io 
is "1"b if the object program contains a runtime symbol table that 
is required by PL/I put data or get data or FORTRAN namelist 
input/output statements in the source program. In this case the 
runtime symbol table cannot be removed. 


table removed 
is "1"b if the object segment originally contained a runtime symbol 
table that has subsequently been removed. 


long profile 
is "i"b if the object segment contains a long profile table. 


greatest severity 
contains the greatest severity level of all error messages issued 
during the compilation of the source program. A value of O means 
that no errors were found during compilation. 


root 
is nonzero only if the object segment contains a runtime symbol 
table; in this case, root is a pointer (relative to the base of the 
symbol header block) to the root block of the runtime symbol table. 
profile 
is nonzero if the object segment contains a profile table. If it is 
nonzero, it is the offset in the linkage section of the table. 
first 


is nonzero only if the object segment contains a statement map; in 
this case, first is a pointer (relative to the base of the symbol 
header block) to the first entry in the statement map. 
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14. last 
is nonzero only if the object segment contains a statement map; in 
this ease, last is a pointer (relative to the base of the symbol 
header block) to the last entry in the statement map. 


15. offset 
is a pointer (relative to the base of the symbol header block) to an 
aligned character string that gives the name of the segment; this is 
the same as the name used for the class 3 definition of the object 
segment. 


16. size 
is the length of the segment name string. 


The PL/I Runtime Symbol Table 


The PL/I runtime symbol table contains information needed to support source 
language debugging and PL/I data-directed or FORTRAN namelist input/output 
statements. Most of the information that the compiler has in its compile-time 
symbol table is placed, in a different format, in the runtime symbol table; this 
permits attributes of a variable such as data type, storage class, or location 
to be determined during execution of the program. If the runtime symbol table 
is present, it follows the PL/I symbol block. 


There are two types of runtime symbol tables: partial tables and full 
tables. 


A partial table is generated when the source program contains data-directed 
input/output statements; it contains information only about variables that are 
transmitted via PL/I data-directed or FORTRAN namelist input/output statements. 
A partial runtime symbol table cannot be removed. 


A full symbol table is generated if the table control argument is specified 
when the source program iS compiled; it contains information about all 
variables, labels, and entries referenced by the source program. A full symbol 
table can be removed from the object program (when binding) if the source 
program does not contain data-directed input/output statements that would 
require a partial table to be generated. 


The existence of a runtime symbol table does not affect the executable code 
normally generated by the compiler. There are no instructions that must 
routinely be executed by the object program in order to support the runtime 
symbol table. In some cases (described later), the compiler generates 
additional code sequences solely because a runtime symbol table is being. 
created, but these extra instructions are not executed unless particular fields 
of the runtime symbol table are actually referenced. 


An internal static variable that has an initial value and is never set is 
normally treated just as if it were aoconstant. If all references to the value 
of the internal static variable can be made using DU or DL modifiers in the 
instructions making the reference, the variable is not assigned a location. If 
all references cannot be made via DU or DL modifiers, the variable is assigned 
one or more locations in the text section. When a runtime symbol table is being 
generated, internal static variables that are initialized and never set are 
always assigned locations in the text section. This does not affect references 
to thes variables since DU or DL modifiers continue to be used wherever 
possible. 
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The runtime symbol table is a list structure that consists of 
interconnected runtime token, runtime block, and runtime symbol nodes. 
Normally, when node A in the runtime symbol table contains a pointer to node B, 
the pointer is relative to the start of the node in which it occurs; such a 
pointer is called a self-relative pointer. The format of the nodes in the 
runtime symbol table are described in the sections that follow. 


THE RUNTIME TOKEN NODE 


The runtime token node holds the name of an identifier used elsewhere in 
the runtime symbol table. The runtime token nodes for all identifiers in the 
runtime symbol table are threaded together on a list that is ordered 
alphabetically by size (all 1 character names before all 2 character names, 
etce.); there are no duplicate names on this list. This ordering is used to 
increase the speed with which the runtime symbol table can be searched. Each 
runtime token node contains a pointer to the runtime symbol node for the first 
variable having the name stored in the runtime_token node. The runtime token 
node has the following format (and appears in runtime _symbol.incl.pl1): 


del 1 runtime_token based aligned, 


2 next bit(18) unaligned, 
2 del bit(18) unaligned, 
2 name, 
3 size fixed bin(9) unsigned unaligned, 
3 string char(0O refer(runtime token.size)) unaligned; 


where: 

Le next 
is a self-relative pointer to the next token on the alphabetic by 
size list of tokens. This field is zero in the last runtime token 
node on the list. 

2s del 
is a self-relative pointer to the runtime symbol node for the first 
identifier having the name stored in this runtime token node. This 
field is zero if there are no identifiers declared with this name. 

or name 


is an ACC string that gives the name of the identifier represented 
by this node (see "The Structure of the Definition Section" for a 
description of ACC strings). 


THE RUNTIME BLOCK NODE 


Each procedure or begin block in the source program has a correspcnding 
runtime_block node in the runtime symbol table. The manner in which these nodes 
are connected reflects the block structure of the source program. Each 
runtime block node contains a pointer to a list of runtime symbol nodes that 
represent declarations defined immediately internal to the block (i.e. internal 
to the block but not internal to any other block contained in the block). These 
declarations correspond to the variables and label or entry constants used in 
the block. The runtime block node has the following format (which appears in 
runtime symbol.incl.pl1): 


del 1 runtime block aligned, 
2 flag bit(1) unaligned, 
2 quick bit(1) unaligned, 
2 fortran bit(1) unaligned, 
2 standard bit(1) unaligned, 
2 owner_flag bit(1) unaligned, 
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where: 
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2 skip bit(1) unaligned, 
2 type bit(6) unaligned, 
2 number bit(6) unaligned, 
2 start bit(18) unaligned, 
2 name bit(18) unaligned, 
2 brother bit(18) unaligned, 
2 father bit(18) unaligned, 
2 son bit(18) unaligned, 
2 map, 
3 first bit(18) unaligned, 
3 last bit(18) unaligned, 
2 entry_info bit(18) unaligned, 
2 header bit(18) unaligned, 
2 chain(4) bit(18) unaligned, 
2 token(0:5) bit(18) unaligned, 
2 owner bit(18) unaligned; 
flag 
is always "1"b and is used to tell this version of the structure 
from an earlier one. 
quick 
is "1"b if the procedure or begin block that corresponds to this 
runtime block node is a quick block that does not have a stack frame 
of its own. By definition, when a quick block is called, pr6 (the 
stack pointer) points at the stack frame shared by the quick block 
in which the quick block allocates its storage. This bit is always 
"O"b in the runtime block that corresponds to an external procedure. 
fortran 
is "1"b if this program was compiled by the FORTRAN compiler. This 
bit is used to tell the programs that access the runtime symboi 
table that array elements are stored in column-major order instead 
of row-major order. The object program contains other places that 
indicate the compiler that processed the program; this bit was added 
to increase the speed with which this information could be obtained. 
Standard 
is "1"b if this object segment is in standard Multics format. Here, 
too, information that is available elsewhere is repeated for the 
sake of convenience. 
owner flag 


is "1"b if this block has a valid owner field. 


skip 
is reserved for future expansion. 

type 
is zero if this runtime block node corresponds to a begin block. A 
nonzero value indicates that the runtime block node corresponds to a 
procedure block. 

number 


in the source 
in which they 
the runtime symbol 


is used to number begin blocks. All 
program are assigned a sequence 
are encountered by the program 
table. 


begin blocks 
number in the order 
that generates 
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10. 


11. 


12. 


15. 


16. 


17. 


18. 
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start 

is a self-relative pointer to the runtime symbol node for the first 
declaration in the block represented by the runtime block node. 
This declaration list gives all level 0 (nonstructure) and level 1 
(top level structure) symbols defined immediately internal to the 
block; the runtime symbol nodes on this list are ordered 
alphabetically by size. The start field is zero if there are no 
declarations in the block. 


name 
is a self-relative pointer to the ACC string that gives the name of 
the block; this field is zero for a begin block. The block compiled 
for an on-unit is a procedure block whose name is derived from the 
name of the condition, e.g. "overflow.1". For historical reasons, 
the name component points at runtime_token.name instead of the 
beginning of runtime_token. 


brother 
is a self-relative pointer to the next runtime block node at the 
same nesting level. This field is zero if there is no other block 
at the same nesting level. 


father 
is a self-relative pointer’ to the immediately containing 
runtime block node of which this block is a son. If the current 
block is the root of the symbol tree, this pointer points to the 
symbol header block. 


son 
is a self-relative pointer to the first runtime_block node contained 
within the current block. This field is zero if the current block 
does not contain any other blocks. 


first 
is nonzero if the object program contains a statement map; in this 
ease first is a self-relative pointer to the entry in the statement 
map that corresponds to the first executable statement in this 
block. If block Bis contained in block A, the entries in the 
Statement map for block B are also contained in the statement map 
entries for block A. 


last 
is a self-relative pointer to the word after the entry that 
corresponds to the last executable statement. Note that zero is a 
meaningful value. 


entry _info 
is nonzero only for a runtime block that corresponds to a procedure 
without its own stack frame (quick = "1"b). It gives the location 
in the stack frame shared by the quick block of the entry 
information block used by the quick block. The format of an entry 
information block is described below. 


header 
is a self-relative pointer to the start of the symbol header block. 


chain 
is a vector of self-relative pointers that point at runtime symbol 
nodes on the declaration list for this block. The chain(i) points 
at the runtime symbol node for the first declaration whose name is 
longer than 2**i; chain(i) is zero if the longest name in the 
declaration list is shorter than 2*¥*i. 
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19. token 
is a vector of self-relative pointers that point at runtime token 
nodes. The token(i) points at the runtime token node for the first 
name longer than 2**i; token(i) is zero if the longest name in the 
token list is shorter than 2**i, 


20. owner 
is a self-relative pointer to the runtime _ block node whose stack 
frame will be shared by this block. This field is valid only if 
owner flag is set. 


THE ENTRY INFO BLOCK 


An entry info block consists of one, two, or three pointers, depending on 
the procedure. It has the following format (declared in quick entry.incl.pl1): 


del 1 quick entry aligned, 
2 return ptr, 
2 argptr ptr, 
2 descptr ptr; 
where: 
‘a return 


points at the return location of the quick block. 


2% argptr 
if present, points at the argument list of the quick block. 


3 descptr 
if present, points at the descriptor list of the quick procedure. 


THE RUNTIME SYMBOL NODE 


Each runtime symbol node in the runtime symbol table corresponds to an 
identifier in the source program. The manner in which these nodes are connected 
reflects the structural relationship of variables in the source program. Level 
QO (nonstructure) and level 1 (top level structure) variables have the 
runtime symbol nodes that correspond to _ them threaded on a list of 
runtime symbol nodes ordered alphabetically by size. 


The format of the runtime symbol node is (declared in 
runtime symbol.incl.pl1): 


del 1 runtime symbol aligned, 

2 flag bit(1) unaligned, 
2 use digit bit(1) unaligned, 
2 array_units bit(2) unaligned, 
2 units bit(2) unaligned, 
2 type bit(6) unaligned, 
2 level bit(6) unaligned, 
2 ndims bit(6) unaligned, 
2 bits unaligned, 

3 aligned bit(1), 

3 packed bit(1), 

3 simple bitt1), 

3 decimal bitct)., 
2 scale bit(8) unaligned, 
2 name bit(18) unaligned, 
2 brother bit(18) unaligned, 
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2 father bit(18) unaligned, 
2 son bit(18) unaligned, 
2 address unaligned, 

3 location bit(18), 

3 class bit(4), 

3 next bit(i4), 
2 size fixed binary(35), 
2 offset fixed binary(35), 
2 virtual org fixed binary(35), 
2 bounds(1), 

3 lower fixed binary(35), 

3 upper fixed binary(35), 


3 multiplier fixed binary(35); 


In the discussion that follows, the term "current identifier" means the 
indentifier represented by the runtime symbol node under consideration, and the 
term "current block" means the block in which the current identifier is 
declared: 


1. flag 
is always "1"b and distinguishes this version of the structure from 
an earlier one. 
Ze use digit 
~ contains the most significant bit of the three bit binary integers 
that identify the addressing units for arrays and offsets. 
3 array units 
contains the low order two bits of a three bit positive binary 
integer that gives the addressing units to be used when computing 
the address of a subscripted array element; this field is meaningful 
only when ndims is not zero. The high order bit is supplied by the 
use digit bit. The possible values for this three bit number, and 
the corresponding factor by which an offset should be multiplied to 
convert to a bit offset are: 
units factor 
O word 36 
1 bit 1 
2 byte 9 
3 half word 18 
4 word 36 
5 bit 1 
6 byte 9 
7 digit 45 
4, units 
contains the low order two bits of a positive binary integer that 
gives the addressing units of the offset field in the runtime symbol 
node. The high order bit is supplied by use digit. The possible 
values and associated conversion factors are the same as for 
array units. 
are type 


contains a positive binary integer that gives the data type of the 
current identifier. The numeric values used to encode the data type 
are the same as the values used in the Multics descriptor, 
supplemented with additional values. See Appendix D of the MPM 
Reference Guide. 


When the identifier is a pictured variable, the real data type is 


given by the picture information block, which can be found by using 
information in the size field of the runtime _symbol node. 


7/81 B-8 AK92C 


10. 
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level 
contains a positive binary integer that gives the structure nesting 
level of the current identifier as determined by the compiler; 
nonstructure variables have level = 0. 


ndims 

contains a positive binary integer that gives the number of array 
dimensions of the current identifier; a value of zero means the 
current identifier is not an array. The ndims gives’ the total 
number of subscripts that must be provided to access an element of 
the array and is the sum of the number of dimensions with which the 
identifier was explicitly declared and the number of dimensions 
inherited from a containing structure. 


aligned 
is "1"b if the current identifier is aligned and is "0O"b if the 
identifier is unaligned. 


packed 
is "1"b if the current identifier is any one of the following: an 
unaligned aggregate of packed data, unaligned arithmetic data, 
unaligned nonvarying string data, or unaligned pointer data. 


simple 
is "1"b if an abbreviated form of the runtime symbol node is being 
used for the current identifier; in this case fields after size in 
the runtime symbol node are not present and the current identifier 
is a scalar with zero offset. If simple is "0"b, all fields in the 
runtime symbol node are present. 


decimal 
is reserved for future expansion. 


scale 
is the arithmetic scale factor of tne current identifier. Although 
stored in a bit (8), it is logically a fixed bin (7). Be warned 
that COBOL and PL/I both define negative scale factors, and that 
PL/I bit to fixed conversion assumes unsigned, not signed. 


name 
is a self-relative pointer to the ACC string that gives the name of 
the current identifier. For historical reasons, the name component 
points at runtime token.name instead of the beginning of 
runtime token. 

brother 
is a self-relative pointer to the runtime symbol node for the next 
identifier at the same structure level; levels O and 1 are 
considered to be the same level. Within a structure (level > 1), 
brother points to the runtime symbol node for the identifier that 
immediately follows the current identifier in the structure; brother 
is zero if the current identifier is the last element in the 
Structure that immediately contains it. Outside of a structure 
(level <= 1), brother points to the next element on the list of 
runtime symbol nodes ordered alphabetically by size. 

father 
is a self-relative pointer to either a runtime block node or a 
runtime symbol node. If level <= 1, father points to the 


runtime block node that represents the block in which the current 
identifier is declared. If level > 1, father points to the 
runtime symbol node for the structure that immediately contains the 
current identifier as a son. 
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son 


is a self-relative pointer to the first son of a structure (the 
runtime symbol node for the first identifier in the structure with a 
level number one greater than the level of the current identifier). 
This field is zero if the current identifier is not a structure. 


location 


class 


usually contains a positive integer L that is used in combination 
with class to determine the address of the current identifier. L is 
normally an offset with respect to the start of a given class of 
storage; its interpretation depends on the value of the class field 
in the runtime symbol node. 


contains a positive binary integer that gives the storage class of 
the current identifier; the possible classes are: 


class Storage class 
‘] automatic; L is the offset at which the current identifier 
is defined in the stack frame associated with the current 
block. 
2 automatic adjustable; the address of the current 


identifier is not known at the time the runtime symbol 
table is created. Location L in the stack frame 
associated with the current block contains a pointer to 
the storage for the current identifier. 


3 based; location is a self-relative pointer to the 
runtime symbol for the pointer used in the declaration of 
the current identifier or is zero if a pointer was not 
Specified. The user must provide a pointer, either 
explicitly at run time or implicitly through the default 
pointer, in order to reference the current identifier. 


4 internal static; Lis the offset at which the current 
identifier is assigned storage in the linkage section 
associated with the current block. 


5 external static; L is the offset in the linkage section of 
a link that points to the current identifier. 


6 internal controlled; L is the offset of the control block 
of the current identifier in the linkage section of the 
current block. 


t external controlled; L is the offset in the linkage 
section of a link that points to the control block for the 
current identifier. 


8 parameter; at Lin the stack frame corresponding to the 
current block there iS a pointer to the storage for the 
current identifier. This storage class is used when the 
current identifier appears in more than one position in 
procedure and/or entry statements in the block. 


9 parameter; L gives the position of the current identifier 
in the argument list provided to the current block. This 
class is used when the current identifier appears in the 
same position in every procedure or entry statement in the 
current block. 


10 not used 
17 not used 
12 text reference; the current identifier is defined at L in 


the text section of the object segment. 
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22. 


23. 


24. 


25. 


26. 
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13 link reference; the current identifier is defined at L in 
the linkage section corresponding to the current block. 


14 not used 
15 not used 
next 
is a self-relative pointer to the runtime symbol node of the next 
identifier having the same name as the current identifier. 
size 
is the arithmetic precision, string size, or area size of the 
identifier. If the identifier is a string or area, it may be an 
encoded value. If the current identifier is a picture variabie, 
size contains the offset at which the picture information block can 
be found in the text. section of the object segment. If the current 
identifier is an offset variable, size is a self-relative pointer to 
the runtime symbol node for the area, if any, associated with the 
current identifier. 
offset 


is the encoded value of the offset of the start of the current 
identifier with respect to the address specified by location and 
class. The units of the offset value are given by the units field 
in the runtime symbol node. This field is not present, and its 
value is assumed to be zero, if the simple bit is "1"b. 


virtual org 
is the encoded value of the virtual origin of an array, in units 
given by array units. Its value should be subtracted from the base 
address specified by location and class. This field is not present, 
and the current identifier is a scalar, if the simple bit is "1"b. 


bounds 

is an array that gives information about each dimension of an array 
identifier, from left to right. The upper bound for the bounds 
array that appears in the declaration is actually a dummy; the true 
upper bound for the bounds array is given by the ndims field. All 
the fields in the bounds array are not present, and the current 
identifier is a sealar, if the simple bit is "1"b. A bound 
structure is declared in runtime bound in runtime _symbol.incl.pli. 


lower 
is the encoded value of the lower bound of this dimension of the 
current identifier. 


upper 
is the encoded value of the upper bound of this dimension of the 
current identifier. 


multiplier 


is the encoded value of the multiplier of this dimension of the 
current identifier. 
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The address of an identifier is calculated in the following manner. The 
base address is determined by the class and location fields. If the identifier 
is "Simple", this is all. Otherwise, the offset field (which may be encoded) is 
multiplied by the conversion factor given by use digit and units to give a bit 
offset, which is added to the base address. If the identifier is not an array 
element, that is all; otherwise, the virtual rigin is computed (an encoded 
value converted to bits by the factor given by use digit and array units) and 
subtracted from the address. The array offset is computed by taking the dot 
product of the subscripts supplied and the multipliers for the identifier. The 
array offset is converted to a bit offset using the array units conversion 
factor, and added to the address previously computed. This gives the final 
address of the data. 


Encoded Values 


The runtime symbol node contains information about the attributes of an 
identifier. In many cases, the value of attributes such as string length, array 
bounds, or address cannot be determined at the time the runtime symbol table is 
created. For example, given the declaration 


del x char(n+m); 


the length of the variable x can be different each time the block in which it is 
declared is entered; the location of x is not known because a variable with 
nonconstant size is allocated when the block is entered. If x were declared 
instead: 


del x char(n+m) based; 


the length of x could be different at each reference. 


The problem of representing nonconstant attributes values is handled by 
encoding the values that can be nonconstant. A field in the runtime symbol node 
that can have a nonconstant value is called an encoded value; it is declared 
fixed binary(35) in the node declaration, but actually has the following format 
(declared in runtime symbol.incl.pl1): 


del 1 encoded value aligned, 
2 flag bit(2) unaligned, 
2 code bit(4) unaligned, 
2 (n1,n2) bit(6) unaligned, 
2°ns bit(18) unaligned; 
If flag “= "10"b, the encoded value is the constant given in the entire word. 
If flag = "10"b, the positive binary integer contained in the code field 
determines the value as follows: 
Code Value 
0 Value is the contents of the word at location n3 in the stack 


frame of the block n1 static levels before the block in which the 
declaration occurs. 


1 Value is the contents of the word at location n3 in the linkage 
section of the block in which the declaration occurs. 


2 Value is the contents of the word with positive offset n1 from 
the word pointed at by the link at location n3 in the linkage 
section of the block in which the declaration occurs. 


3 Value is n3 plus the contents of the bit offset field of the 


pointer used to access the variable, which must be based. This 
encoding was only used by the compiler before version 2 EIS. 
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Value is the contents of the word with positive offset n2 based 
on the pointer at location n3 in the stack frame n1 static levels 
before the block in which the declaration occurs. 


Value is the contents of the word with positive offset n2 based 
on the pointer at location n3 in the linkage section of the block 
in which the declaration occurs. 


Value is the contents of the word with positive offset n2 based 
on the pointer with positive offset n1 from the word pointed at 
by the link at location n3 in the linkage section of the block in 
which the declaration occurs. 


Value is the contents of the word with positive offset n2 based 
on the pointer used to access the variable, which must be based. 
This encoding is used for refer extents. 


Value is the value returned by the internal procedure at location 
n3 in the text section of the block in which the declaration 
occurs. This procedure is compiied as if it were declared in the 
block in which the declaration occurs. This encoding is used 
whenever one of the other more specific encodings cannot be used. 
The calling sequence of this procedure is 


del f entry(ptr) returns(fixed binary(24)); 
value = f(refp); 


where refp is the pointer that could be used to access a based 
variable. Note .that this procedure is never called by the 
executable code in the object program, it is used only by the 
programs that reference the runtime symbol table. 


Value is the contents of the word with positive offset n3 from 
the start of argument n2 of the procedure n1 static levels before 
the block in which the declaration occurs. 


Value is the contents of the word with positive offset n3 from 
the word pointed at by the pointer that is argument n2 of the 
procedure ni static levels above the block in which the 
declaration occurs. 


Value is the contents of the size field of descriptor n2 of the 
procedure ni static levels before the block in which the 
declaration occurs. 


Value is the contents of the word with positive offset n3 from 
the start of descriptor n2 of the procedure n1 static levels 
before the block in which the declaration occurs. 


Value is the size field at positive offset n2 from the start of 
the descriptor for a controlled variable. For all encodings 
having to do with controlled variables, if ni = 0 the variable is 
internal, if nl = 1 it is external. For an internal controlled 
variable a pointer to the descriptor (control_block.descriptor) 
is located at n3 in the static secion. For an external variable, 
a ptr to the descriptor ptr is at n3 in the linkage section. 


Value is the contents of the word with positive offset n2 from 
the start of the descriptor for a controlled variable. The 
descriptor is located in the same manner used for type 13 
encoding. 
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15 Value is the contents of the word with positive offset n2 from 
the start of a controlled variable. If ni = O the controlled 
variable is internal and its control block is located at n3 in 
the linkage section of the block in which the declaration occurs. 
If n1 = 1 the controlled variable is external and location n3 in 
the linkage section of the block in which the declaration occurs 
contains a pointer to the control block. The data itself is 
found using the data pointer of the controlled variable control 
block. 


Controlled Variable Control Block 


The format of the control block for a controlled variable is given in 
etl _block.incl.pli: 


declare 1 control_block aligned, 


2 data ptr, 
2 descriptor ptr, 
2 previous ptr; 


where: 
ls data 
points at the current generation of the controlled variable. It is 
null if the controlled variable does not have a current generation. 
2. descriptor . 
points at the descriptor for the current generation of the 
eontrolled variable. 
Ss previous 


points at the control block of the previous generation of the 
controlled variable. It is null or points to a null ptr if there is 
no previous generation. 


Picture Information Block 


A picture variable of any type is stored in edited form as a character 
String. Each picture variable has an "associated value" that gives the value of 
the picture variable in internal form, either as a character string or as a 
decimal number. When the current identifier is a picture variable, the size 
field in the runtime symbol node specifies the location of the picture 
information block, whose format is (declared in picture image.incl.pl1): 


del 1 picture info based aligned, 

2type fixed binary(8) unaligned, 

2 prec fixed binary(8) unaligned, 

2 scale fixed binary(8) unaligned, 

2 piclength fixed binary(8) unaligned, 

2 varlength fixed binary(8) unaligned, 

2 scalefactor fixed binary(8) unaligned, 

2 explength fixed binary(8) unaligned, 

2. aritt char(1) unaligned, 

2 chars char(0O refer(picture info.piclength)) aligned; 
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where: 


leg type 
is the true data type of the current identifier according to the 
following encoding: 
type data type named constants 
in picture image.incl.pli 
a4 character string picture char type 
25 real fixed decimal picture realfix_ type 
26 complex fixed decimal picture complexfit type 
27 real float decimal picture realflo type 
28 complex float decimal picture complexflo type 
26 prec 
is the arithmetic precision or string length of the associated 
value. Note that the length of a character picture variable must be 
constant. 
3% scale 


for arithmetic picture variables is the number of digits, if any, 
after the "v" in the picture constant minus scale factor (see 
below). 


4, piclength 
is the length of the normalized picture constant string. 


Bie varlength 
is the length of the edited form cf the picture variable in 
characters. Note that the length of a picture variable must be 
constant. 


6. scalefactor 
is the picture scale factor. 


re explength 
is the length in characters of the exponent field of a floating 
point picture variable. 


8 drire 
is the picture drifting character. It is blank if the picture 
constant does not specify a drifting field. 


9. chars 
is the normalized picture constant. 


SPECIAL RUNTIME SYMBOL DATA TYPE CODES 


type data type 

Ou label constant (used in symbol tables only) 

25 internal entry constant (used in symbol tables only) 
26 external entry constant (used in symbol tables only) 
27 external procedure (used in symbol tables only) 


63 picture (used in symbol tables only) 


These types are used in runtime symbol values only, and not in argument 
descriptors. The user is referred to Std_descriptor_types.incl.pl1, which gives 
named constants for these codes. See Appendix D of the MPM Reference Guide for 
more information. 
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The Statement Map 


The statement map contains information about each statement in the source 
program for which instructions were generated. The statement map is normally 
placed after the runtime symbol tabie, if the table is present. All the entries 
are contiguous. Each entry in the statement map has the following format 
(declared in statement _map.incl.pl1): 


del 1 statement map aligned based, 
2 location bit(18) unaligned, 
2 source id unaligned, 
3 file bit(8), 
3 line bit(14), 
3 statement bit), 
2 source info unaligned, 
3 start bit(i8), 
3 length bit(9); 
where: 
1. location 


is location in the object segment of the first instruction generated 
for the statement that corresponds to this entry in the statement 
map. 


2s source id 
describes the line on which the statement begins. The last entry in 
the statement map is a dummy that has string(source_id) = (27)"1"b. 


34 file 
contains a positive binary integer that specifies the number of the 
source segment in which the current statement is contained (see "The 
Source Map"). 

oe line 
contains a positive binary integer that specifies the number of the 
line on which the current statement begins. The first line in a 
file is number 1. 

or statement 
contains a positive binary integer that specifies the position of 
the current statement on the line in which it begins. The first 
Statement on a line iS number 1. 

6 source info 
specifies the starting position and length of the string of 
characters that are the source for the current statement. 

re start 


contains a positive binary integer S that specifies the number of 
characters that precede the first character of the source of the 
current statement (see below). 


8. length 
contains a positive binary integer L that gives the number of 
characters occupied by the current statement in the source file; a 
statement is assumed to be entirely contained in a single segment. 
If string is the contents of the source file that contains the 
current statement considered as a single string, the source string 
for the current statement is substr(string,S+1,L). 
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absentee 
assembly 
alm_abs 6-30 
default absentee queue 7-197.2 
access control 
access isolation mechanism 
econvert_aim_ attributes 7-24 
aecess isOlation mechanism (AIM) 
aim_ check 7-6 
aim_ check __$equal 7-6 
aim_ ~eheck _$greater 7-6 
aim_ - cheek $greater_ or_equal 7-7 
get_ privileges. 7-68 
read allowed 7-177 


read _write allowed 7-179 


system_ info _$access _ceiling 7-200 


system_ info “$category_ names 7-201 
system_info ~ $level names 7-200 
write allowed 7-214 
access modes, directories 
ev_dir_mode_ 7-34.1 
access modes, segments 
cv_mode_ 7-38.1 
add ACL entry 
mbx_set_acl 6-50 
msf "manager $acl_add 7-164 
copy_acl_ 7-28.1 
delete ACL entry 
mbx_delete_acl 6-45 
msf_ manager _ $acl_delete 
effective access 
read allowed 7-177 
read ~write_ allowed 
write_ allowed 7-214 
initial ACL for new directories 
hes $add_dir_inacl_entries 7-72 
hes $delete_ dir_ inacl _entries 
7-77 
hes $list_dir_inacl 7-97 
hes ~$replace_ dir_ inacl 7-103 
initial ACL for new segments 
hes $add_inacl_entries 7-74 
hes  $delete_ inacl entries 7-78 
hes  $list_ inacl 7-99 
list ACL 
mbx list acl 6-48 
msf_manager_$acl_ list 7-162 
mailbox 
mbx delete acl 6-45 
mbx_set_acl 6-48 
‘multisegment file ACL 
msf_manager_$acl_add 7-164 


7-165 


7-179 


access control (cont) 
multisegment file ACL 
msf manager_$acl_delete 7-165 
msf | _manager _ ~$acl_ list 7-162 
msf | manager |: ~$acl_ _replace 7-163 
privileges 
get_privileges 7-68 
replace ACL 
hes $replace_dir_inacl 
hes _$replace_ inacl 7- ro4 
msf manager $acl replace 
rings - . 
get_ring 7-70 
hes _$get_ dir_ring brackets 
hes _$get_ ring_ brackets 7-87 
hes _$set_ dir_ring brackets 
hes  $set_ _ring_ brackets 7-110 
set _dir_ring_ brackets 6-63 
set_ring_ brackets 6-66 
status 
hes $get_user_effmode 
terminals 
dial_manager_$registered_server 


6-38 


-103 
7-163 


7-93 


dial_manager_ call 


accounting 
obtaining usage 
system_info_$abs _prices 7-199 
system_ info _$device prices 7-196 
system info _$io_prices 7-199 
system info $prices 7-195 
shift definition table 
system_info_ $shift_table 
storage quota 
hes $quota_move 7-101 
hes $quota_ read 7-102 


7-198 


active function 
error messages 
active fne_err_ 7-3 
allocation 
area 
get_system_free_ area_ 


ALM procedures 
transfer of control 2-9 
answering service 
dial facility 
convert dial _ message _ 
dial_manager_ 7-48 
dial" manager_call 6-38 


7-25 
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archive 
archive_sort 6-32 


reorder archive 6-60 
area 

area info _ 7-8 

area status 6-33 

create area 6-35 

define_area_ 7-45 


free storage 
get_system_free_area_ 

release area 7-780 

set _system_ storage 6-67 

set_ user _storage 6-70 


1-71 


argument list 2-13 
data type codes 
examining 

decode descriptor _ 
format 2-13 

‘header 2-13 

manipulating 
get_entry arg descs 
get_entry point_dcl_ 


B-15 
7-43 


7-63.2 
7-64.1 


arithmetic 
assign 7-15 
assign | _$computational_ 
assign. ~ round 7-16.11, 
assign ~truncate_ 7-16.1 


7-16 


ARPANET 
system_info_$ARPANET_host_number 
7-201 


assembly 
alm 6-4 
alm_abs 6-30 
asterisk 
array bounds 
extent 2-18 


2-18 


auto call channel 
telephone 
dial_manager_$dial_out 7-49 
dial _manager_ ~eall ~6-38 


B 
bind map 1-34 
binder 
see also object segment, bound 
bound segments 
see also object segment, bound 
bound segments, structure of 1-31 
brief mode 
login 3-5 
bulk I/0 
offline 
dprint 7-55.1 
iod_info_ $driver_access_name 
7-138 
iod_info_$generic_type 7-138 


bulk I/0 (eont) 


i-2 


offline 


system_info_ $io_prices 7-199 


call 
generating 2-9 
short. 2-10 


call (interprocedure) 
pll_operators 2-9 


2-10 


calling sequence 2-9 
get_entry_arg_descs_ 


call operator 


7-63.1 


character set 
ascii to ebcdic_ 
ebedic_ to_ ascii_ 


cleanup 
area 
release area_ 
bit count 
msf_manager_$adjust 7-161 
process 
execute epilogue 
releasing stack frame 
unwinder_ 7-212 
run units 


7-180 
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add_epilogue_handler 7-182.19 
run 7-182 
run “$environment_ info 7-182. 


translator temporary segment 
tssi_$Sclean_up_ file 7-211 
tssi _$clean_ _up_ segment 7-211 


closing 
multisegment file 


msf_ manager _$close 7-162 


combined linkage region (CLR) 


print_linkage usage 6-59 
command environment 
entry value 
get_entry_name 7-64 


system free storage 


get_system_free area_ 7-71 
comparison 
star name 
match_star_name_ 7-150 
component 
bound segment 
component_info 7-18 
component __ info _$name 7-18 


component_info $offset e 18 
display_ component_ name 6-39.1 


component_info_ 7-18 


condition 
alrm 3-3, 3-4 
any other 3-4 
eput 3-3, 3-4 
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condition (cont) 
error messages 


active_fne_err_ 7-3 
condition _ interpreter_ 7-21. 
convert_ status _ code_ ~7=-28 
find condition _ frame_ 7-60 
find ~eondition_ info 7-61 
handling 
continue_to_ signal 7-23 
find _condition_ frame_ 7-60 
find condition info 7-61 


hes $get_exponent_control 7-83.1 


hes ~$set_ exponent _ control 7-107.1 
sct_ manager 7- 182.21 
sus_Signal_handler_ 7- -192.1 


unwinder_ 7-212 

machine conditions 
prepare _mc_ restart _$replace 
prepare me restart $retry 7-174 
prepare_me_ restart _$tra 7-175 

- raising 

active _fne_ err 7-3 
signal 7-182.28 

signal 6-70 

trm_ 3-3 

wkp_ 3-3 


convention 
equal 
get_ equal _ name_ 7-65 
star 
eheck_star_name_ 7-16.4 
check _ star_ name _$entry 7-17 
check _star_name $path 7-16.4 


hes _$star_ dir list 7-120 
hes $star_ list 7-115 
match_star_name_ 7-150 
star_ 
hes $star_ 7-113 
conversion 


access control 
convert aim attributes_ 
ev dir mode 7-34.11 
ev _mode_ 7-38.1 
addresses 
ev_entry 7-35 
ev_ptr_ 7-41 
ev_ptr_$terminate 
argument 
decode descriptor_ 
character set 
ascii_to_ebedic_ 
ebedic to ascii_ 
ev_bin _$dec_ 7-31 
ev bin ~$oct 7-32 
equal name 
get_equal 
general 
assign = 7-15 
assign _$computational _ 
assign_ ~round 7-16.1- 
assign truncate_ 7-16.1 
location to name 
get_ entry name 
numeric to string 
assign 7-15 
assign _$computational _ 
assign round_ 7-16.1_ 
assign_ _truncate_ 7-16.1 
ev_bin_ 7-31 


7-24 


7-41 
7-43 


7-11 
7-57 


_name_ 7-65 


7-16 


7-64 


7-16 


7-175 


i=3 


conversion (cont) 

string to numeric 
assign 7-15 
assign ee compuat tonal 
assign round 7-16. 
assign _ ~truncate_ T- a 
char_to_ numeric_ 7-16.3 
Cv dec_ 7-33 . 
cv dec | check 7-34 
ev_hex 7-37 
Cv. hex check 7-38 
Cv “eet 7-39 
CV oct check_ 7-40 

User id 
ev_userid_ 


7-16 


7-42.8 


copy switch 
copy switch off 6=-34.1 
copy switch on 6-34.2 


cost-saving features 
program tuning 
print_linkage usage 6-59 
CPU 
usage 
system_info_$abs prices 7-199 
system_ info ~$prices 7-195 
timer_manager $cpu_call 7-204 
timer _ _manager _$epu_ call_inhibit 
7-205 
timer_manager $cpu_wakeup 7-205 
timer manager . ~$reset _cepu_call 
7-205 
timer_manager_ $reset_cpu_wakeup 
7-20 


daemon 
offline I/0 
dprint_ 7-55.1 
data base 
Sys_info 8-2 
time table $zones 8-4 
debugging 1-2 
bound segment 
binder symbol block 
print_bind_ map 6-56 
bound segment offset 
display component 
name 6-39.1 
error mesSages 
active fne err T=3 
condition _interpreter_ 
convert status code_ 
inspecting segments 
dump segment _ 7- 56 
linkage section 
print linkage usage 
object map 1-25 
see also area, error handling, 
external variables, object 


1-32 


7-21 
7-28 


6-59 


segment, run unit, stack 6-59 
Stack trace 
find_ condition info _ 7-61 
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default 
error handling 
signal 6-70 
signal _ 7-182.28 


default error handling 


condition_interpreter_ 7-21 
continue to Signal 1-23 
find_ condition info_ 


7-61 


default working directory 


get_default_wdir_ 7-62 
definition 
get_definition_ 7-63 
definition relocation codes 1-29 
definition section 1-1, 1-23, 1-31, 


1-32, 1-33 
.- definition hash table 
dynamic linking 1-4 
header 1-7 
implicit 1-29 
relocation 1-28 
see also relocation 
unstructured area 


1-14 


1-5 


deleting | 
ACL entries 
hes $delete dir _inacl_ entries 
T-77 


hes_$delete_inacl_ entries 7-78 

mbx_ _delete_ ‘acl 6-45 

msf manager _| $acl_delete 7-165 
directory | 

dl handler _ 7-54 

hes | $del_ dir_ tree 7-76 
entries 

dl_handler_ 7-54 


initial ACL entries 
hes $delete_ dir_inacl_entries 
7-77 


hes $delete_inacl_entries 7-78 
search rules 
hes $initiate_ search rules 7-95 
descriptor 1-3 
argument 2-16 
decode descriptor 7-43 
get_entry_arg desecs_ 7-63.1 
directory 
access control 
copy_acl 7-28.1 
hes _$delete_ dir_inacl_entries 
T-77 
hes $get_dir_ring_ brackets 7-83 


hes | _$replace_ dir_ Inacl 7-103 


hes  $set_ dir “ring _ brackets 7-105 
ACL fér new directories 
hes $add_dir_inacl_entries [7-72 


hes $list_ dir_ inacl 7-97 
author 


hes $get_author 7-81 
default working 

get_ default_wdir_ 7-62 
deleting 

hes $del_dir_tree 7-76 


‘listing contents 
hes $star_ 7-113 


directory (cont) 


i-4 


listing contents 


hes $star_dir list 7-120 

hes $star_ list_ T=-115 
quota 

hes $quota_move 7-101 


hes _$quota_ read 7- 102 
safety switch 

hes $get_safety_sw 7-88 

hes $set_ _safety_ sw 7-111 
working 

get_default_wdir_ 7-62 


dl_handler_ 7-54 


dynamic linking 1-4, 1-16 


entry operator 2-10 
entry point 
external 

name 
get_entry name_ 
transfer vector 


1-3 


7-64 
1-4 
entry sequence 1-3, 1-27 
entry value 

generation from string 

cv_entry 7-35 


entryname 
conversion from equal name 
get_equal_ name_ 7-65 
match with star name 
match_star_ name _ 7-150 
equal 
convention 
get_equal_name_ 7-65 
error handling 
active fne_err_ 7-3 
add_epilogue_ handler _ 7-5 
condition_ interpreter 7-21 
continue to _Singal_ 7-23 
convert status code 7-28 
find_condition_ info_ 7-61 
prepare _ me restart _ 7-174 
signal 6-70 
Signal 7-182.28 
sub_err_ 7-186 


exec com 3-5 


external symbol 

name 
get_entry name_ 7-64 

external variables 
delete external variables 6-36 
get_ external variable_ 7-66.2 
list external variables 6-39.2 
reset external variables 6-62 
set_external_variable_ 7-182.24 
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file control block 
msf_manager_$close 
msf __manager ~$open 


7-162 — 
7-157.2 | 


tssi $clean - up_ file 7-211 
tssi_$finish_file 7-209 
tssi_$get_file 7-208 
find_condition_frame_ 7-60. 
find_condition_info_ 7-61 
free storage 
get_system_free_area_ 7-71 


gate segment 
entry point transfer vector 
1-4 


1-2, 


‘generated code conventions 1-27 


H 
hardware 
machine language 
alm - 
alm_abs 6-30 
hash table 1-14 
hash_index_ 7T-71.1 
hes $del_dir_tree 7-76 
I 
I/0 


attach description 
attachment 3-3 
control block 


4-4, 4-7, 4-9 


pli_io $get_iocb_ ptr 7-172 
error messages 

active fne_err_ 7-3 

condition interpreter 7-21 

convert_status code_ 7-28 


sub_err_ 7-186 


I/O control block (IOCB) 4-1, 4-3, 
structure 4-3 
T/O module 4-1 
implementation rules 4-6, 4-7, 
4-8, 4-9, 4-10 
_offline (daemon) 
dprint. 7-55.1 
iod_ info _S$driver_access_ name 
7-138 
iod infs _$generic _type 7-138 
open data 4-4 
open description 4-4 
“operations 4-4, 4-5, 4-7, 4-8, 4-9 
-rings 


eross ring io $allow_cross 7-30 


I/0 (eont) 


initial command line 


i-5 


synonym attachment 4-5, 4-7 


I/O control block 4-2 
3-5 
internal static offset table (ISOT) 


internal storage 
see storage classes 


interprocess communication 
event channel creation 
ipe_ $create_ ev chn 
ipe_. ~$del ev call chn 
ipe $decl_ev wait chn 7-143 
event channel deletion 
ipe $delete_ev_chn 7-142 
event channel” management 
ipe $cutoff 7-144 
ipe_ ~$drain_ chn 7-143 
ipe ~$mask ev_ calls 7-146 
ipe $read_ev_chn 7-148 
ipe_. ~$reconnect 7-144 
ipe_ ~$set call _prior 
ipe_ ~$set wait _prior 
ipe ~$unmask _ ev_calls 
request wakeup 
timer_manager $alarm_wakeup 7-204 
timer _manager ~$epu _wakeup 7-205 
timer | manager _. _$reset_ alarm_wakeup 
7-206 
timer eenee ne eee rec PULNakeup 


7-141 
7-142 


7-145 
7-145 
7-146 


send wakeup 
hes $wakeup 7-122 

wait for wakeup 
ipe_$block 7-146 
timer_manager_$sleep 7-203 


interuser communication 
mailbox commands 


mbx_ create 6-43 
mbx _delete acl 6-45 
mbx list ad 6-48 
mbx _ _set_ acl 6-50 
iod info 7-138 
iod info _$driver_access name 7-138 
iod_info _$generic_ type 7-138 
ips mask 
creation of 
create ips mask_ 7-28.2 


replacement of 
hes $reset_ips_ mask 7-104.1 
hes ~$set automatic _ips_mask 
7-104.2 
hes $set_ips_ mask 7-107.2 
value of 
hes $get_ips_ mask 7-83.2 


ISOT 


see internal static offset table 
(ISOT) 
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language 

assemblers 
alm 6-4 

translator utilities 
tssi_$clean_up_file 7-211 
tssi ~$clean_ "up_segment . 7-211- 
tssi_$finish_ segment 7-208 
tssi “$get_ file 7-208 

tssi _$get_ segment 7-207 


languages 
absentee compilation 
alm_abs 6-30 
libraries 


search rules 
hes $get_system_search_rules 
hes ~$initiate_ search_ rules 


7-91 
7-95 
link area 1-30 
linkage offset table (LOT) 2-8 
linkage relocation codes 1-30 
linkage section 1-1, 1-2, 1-15, 1-23, 


1-31, 1-32 
dirst reference 1-2 


first reference 1-18 
header 1-16 
internal static 1-15 


relocation information 1-30 
links 1-17 
addresses 1-2 
array 1-31 
author 
hes $get_author 7-81 
elimination by binder 
information 
print_ linkage usage 
resolution 1-3 
self-referencing 
status 
hes $star_ 7-113 
hes _$star_ “dir list_ 7-120 
hes  $star_ list_ T=-115 
system 1-12 
target pathname 
hes $get_link_ target 7-84 
type 6 1-12 


1-30, 1-33 
6-59 
1-10 


listener 
called by 
default_error_handler_ $wall 3-4 


listing 

directory contents 
hes $star_ 7-113 
hes $star_ dir_list_ 7-120 
hes $star_ list_ 7-115 

initial ACL for new directories 
hes $list_dir_inacl 7-97 

initial ACL for new segments 

_ hes $list_inacl 7-99 

mailbox ACL 

"  mbx_list_acl 6-48 


i-6 


listing (cont) 
multisegment file ACL 
msf_manager_$acl_ list 7-162 


listing segment 
translator interface 

tssi_$clean_up_ file 7-211 
tssi _$clean_ _Up_ “segment 7-211 
tssi _$finish_ file 7-209 
tssi_$finish segment 7-208 
tssi ~$get_ file 7-208 
tssi ~$get_ segment 7-207 


login 3-1 


LOT 
see linkage offset table (LOT) 


machine conditions 
examining 


find _condition_info_ 7-61 
machine language 
alm 6-4 
alm_abs 6-30 
mailbox 
access control 
mbx_ delete acl 6-45 
mbx_ list acl 6-48 
mbx_ set_ ‘acl 6-50 
messages 
error 
active fne err 7-3 
condition _interpreter_ 7-21 
convert status_ code 7-28 
find_ condition, info_ 7-61 


multisegment file 
access control 
copy_acl_ 7-28.1 
msf _manager_ $acl_add 7-164 
msf manager _. _$acl_delete 7-165 
msf | _manager_ ~$acl_ list 7-162 
msf manager _$acl_replace 7-163 
bit count 
msf_manager_$adjust 7-161 
msf_ manager $open 7-157.2 
closing 
msf_manager_$close 7-162 
7-158 


finding next component 
msf_ manager_$get_ptr 
msf manager_ _$msf_get_ptr 7-159 
opening 


msf_manager_$open 7-157.2 


name 
duplication 
nd_handler_ 
star- 
check star_name_ 7-16.4 
check star_name $entry 7-17 
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name (cont) 
star 
check_star_name _$path i 16.4 
hes _$star 
dir list_ 7-120 

hes _$star_ 7-113 
hes $star_ list_ 
match_ star_ name_ 


7-115 
7-150 


names 
access class 
system_info_$category names 
system_ info _$level_ names 7-200 
equal 
get_equal_name_ 7-65 
external symbol (entry point) 


get_entry_name_ 7-64 
print _link_ info 6-57 
installation 
system_info_ $installation_id 
7-193 


system_info_$titles 7-193 
system version 
system_info $sysid 7-193 
-nd_handler_ 7-165.1 
network — 
system_info_ $ARPANET_ host_number 
-201 


new_proc 3-1 


no_start_up attribute 3-5 


object component 
status 
component_info_ 7-18 
1-25 
1-25 


object map 1-2, 
structure of 
object segment 1-2, 1-16 

bind map 1-34 
bound 1-1, 1-14, 1-31, 
binder symbol block 1-33 
defined 1+31 
definition section 1-33 
display component _name 6-39.1 
internal references 1-33 
link resolution 1-33 
links 1-30 
nonrelocatable 1-34 
print bind map 6-56 
definition section 1-1, 
1-28, 1-31, 1-32 
defined 1-4 
entry bound of gate 
entry sequence 1-2, 
first reference 12, 
gate 1-2, 1-4 
linkage section 
1-16, 1-23, 
1=32 . 
relocation information 
° 1-31 
self-referencing 


1-33, 1-4.1 


1-7, 1-23, 


1-4 
127 
1-16 


(a1, 1204 
12293, 1-30; 
1-23, 1-30, 


1-11 


7-201 


object segment (cont) 


Standard 1-1 
Static section 1-2, 1-11, 1-30 
Jeuauus 

display_component name 6-39.1 


object_info_$brief 7-166 
object_ info _$display 7-166 
object info $long 7-167 
print _bind_map 6-56 
print_ link_ info 6-57 
structure 1-31 
symbol block 1-34 
symbol section 1-2, 
1-30, 1-31, 1-32 
test section 1-1, 1-27 
text section 1-11, 1-23, 
translator interface 
tssi_$clean_up_file 7-211 
tssi _$clean_ _Uup_ "segment 7-211 
tssi ~$finish_ file 7-209 
tssi_$finish_segment 7-208 
tssi _$get_ file 7-208 
tssi_$get_ segment 7-207 


1-11, 1-23, 


1234, 


object segment, standard 
break map 1-2 
definition section 
hash table 1-14 
format of 1-1 
gate segment 1-4 
linkage section 
Static section 1 
symbol section 1 
text section 1-1 


1, 1-15, 1-16 
1-15 
1-20 


“2, 143 


Wes 
-2, 
-2, 
oa 
opening 

multisegment file 

msf_manager_ $open 7-157.2 

operator 

call 2-10 

entry 2-10 

push 2-11 

return 2-11 


short_call 
short_return 


2-10 
2-11 


page faults 
segments 
mhes $get_seg_ usage 7-156 
mhes $get_seg_ usage ptr 7-156 
parameter descriptors 2-18 
per-process data 1-3 
linkage section 1-16 
Stack 2-1 


per-ring data 2-1 
internal storage offset table (I 
2-8 
linkage offset table (LOT) 
stack segment 2-1 


2-8 


perprocess data 


linkage section 1-2 


1-32 


SOT) 
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perprocess data (cont) 
see also linkage section, object 
segment, and stack 


PLT 
see process initialization table 
(PIT) - 
PL/I 
T/0 


plil_io $get_iocb ptr 7-172 
pl1_operators 2-9 


pointer value 
generation from string 
ev_ptr_ 7-41 
CV SpE “$terminate 7-41 


prelinking 1-2, 1-30, 1-33 


prices 
system_info_$abs prices 7-199 
system_info _$device prices 7-196 
system_ info ~$io _prices 7-199 
system_ info _$prices 7-195 


printing 
offline 
dprint 7-55.1 
iod_ info _$driver_access name 
7-138 

iod_info_$generic_type 7-138 
system_info_$io_ prices 7-199 

terminal 
dump _segment_ 7-56 


process 
access privileges 
get_privileges_ 7-68 
creation 3-1 
initialization of 3-1 
overseer 3-1, 3-2, 3-4, 3-5 
termination 
terminate process 7-202 


process initialization table (PIT) 
3-1 


process overseer 3-1, 3-2, 3-4, 3-5 


process, initialization of 3-1 


punched cards 
offline output 
dprint 7-55.1 
iod_info_$driver_access_ name 
7-138 
iod_info _$generic_ type 7-138 
system_ info _$io_prices 7-199 


push operator 2-11 
creation of stack frame 2-11 


queue 
“absentee 
alm_abs 6-30 


queue (cont) 
I/O daemon 
dprint_ 
I/Odaemon 
system_info_$io_prices 7-199 


1-55.1 


quit 


abort execution 
signal 7-182.28 
unwinder_ 7-212 

enabling 3-5 

handling 3-5 
continue to_signal 7-23 
find _condition_ info_ 7-61 


quit_enable order 
see quit, enabling 


quota 
storage 
hes $quota move 7-101 
hes $quota_read 7-102 


quote doubling 
requote string 7-181 


RCP 
see resource control package (RCP) 


referencing dir 
hes $get_search_rules 7-90 
hes _ _$get_ system_ search rules 7-91 
hes $initiate_search_rules 7-95 


register 
machine conditions 
condition_interpreter_ 7-21 
find _condition info ~ 7-61 
prepare_mec_restart_$replace 7-175 
prepare mc _restart _$retry 7-174 
prepare | me restart “$tra 7-175 
pointer register 0 
operator segment pointer 2-13 
pointer register O (PRO) 
Operator segment pointer 2-10 
pointer register 4 (PR4) 
linkage pointer 2-10 
pointer register 6 
Stack frame pointer 2-13 
pointer register 7 (PR7) 
Stack base pointer 2-13 
Saving registers 2-10, 2-11 


relocation 1-2, 1-23 
codes 1-28 
linkage section 1-30 
relocation blocks 1-23, 1-24 
symbol section 1-30 
text section 1-27 


requote_ string 7-181 
resource control package (RCP) 
interface 


resource control $cancel 7-182.2 
resource_ ~eontrol _$reserve 7-182 
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resource control package (RCP) (cont) 
resource attribute specifications 
and descriptions 
ev_rep attributes _$from_ string 


T=42.3 


ev rep oe $from string rel 


eee ae 
cv rep_ a pues $modify 7-42.3 
ev rep attributes $modify_ rel 


T-H2.5 
ev rep attributes $protected 
Change 7-42.6 


CV SPeD attributes Sac eee 
_implications 7-42. 
CV ESD attributes $test_ Ce 
7-42.7 
ev rep attributes _$to_string 
~' Tol2,2 
resource description 
interpret resource desc 
‘resource types - = 
resource info 7-182. 13 
resource info $canonicalize name 
7-182.16 


7-137.1 


resource info $defaults 7-182. 15 
resource info $get type 7-182.13 
resource info $limits 7-182. 13 


resource info ~$lock_ on_ release 
7-182.16— 


resource info $mates 7-182. 14 
restarting 
fault 
prepare me restart $retry 7- 174 
prepare mc_ “restart | _$tra 7-175 
return dperator: 2-11 
rings 
access control 
hes $get ring brackets 7-87 


hes $set dir ring brackets 7-105 

hes $set ring brackets 7-110 
access control(ring brackets) 

hes $get_ dir ring brackets 
execution — 

get ring 7-70 

hes $get dir _ring brackets 

hes | $get_ ring_ brackets 7-87 
I/O 7 

cross ring io $allow cross 


7-83 


7-83 


7-30 


run units 
add epilogue handler 7-5 
run 7-182.19 
run $environment info 
see also cleanup 


7-182.19 


search rules 
initialization of 3-2 
working directory 3-2 
obtaining 
hes $get_ search _ rules 
setting 
_ hes $initiate search rules 
site-defined keywords _ 
hes $get_ system search rules 


7-90 
C295 
7-91 


segment 
access control 


copy acl 7-28.1 
hes $get_ ring brackets 7-&7 
- hes” $set_ ring brackets 7-110 
set dir ring brackets 6-63 
set ring brackets 6-66 
ACL for new segments 
hes ¢$add inacl entries 7-74 


hes $delete inacl entries 7-78 
hes $list inacl 7-99 
hes $replace inacl 7-104 
author 
hes $get author 7-81 
bit count author 
hes $get be author 7-82 
copy Switch ~— 
copy switch off 6-34.1 
copy switch on 6-34.2 
entry point bound 
hes $set_ entry bound seg 7-107 


length 

print link info 
maximum length 

hes $get max length 7-85 

hes ¢get max length seg 7-86 

hes $set_max length 7-108 

hes $set max _length_ seg 7-109 
safety switch ~ 

hes $get safety sw 7-88 

hes ¢get safety sw seg 7-89 

hes $set safety sw 7-111 

hes $set safety sw seg 7-112 
see also object ségment, stack 
unique identifier 

hes $get_ uid seg 7-92. 


6-57 


segments 
page faults 


mhes $get seg usage 7-156 


mhes $get seg usage ptr 7-156 
usage __ - 
mhes $get seg usage 7-156 
mhcs $get seg usage ptr 7-156 
set user storage 6-69 
seven-punch cards 
dprint 7-55.1 
shift 
accounting 
system info $shift table 7-198 
short return operator 2-11 
shot call operator 2-10 


shutdown 
last system shutdown 


system info $last shutdown 7-200 
next system shutdown 
System info $next shutdown 7-195 
sorting 
archive 


archive sort 6-32 
reorder archive 6-60 


source map. 1-22.1 
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special directories 

default working directory 
get_default_wair 7-62 
home directory 3-% 

search rules 
hes $get_ search rules 7-90 
hes $initiate_search_rules 

working directory 
get_default wdir_ 


T-95 
7-62 


stack 2-1 
frame 2-i, 
creation o 
header 2-1 
releasing frame 
unwinder_ 7-212 


2a, D5 
f° 229, 2213 


stack and link area 2-1 


internal static offset table 2-8 


linkage offset table 2-8 
-Multics stack 2-1 
Multics stack frame 2-5 
stack header 2-1 
star convention 
check_star_name 7-16.4 


check_ star_ name _$entry T-17 
check_ star_ name $path 7- 16.4 
get_ equal __ name 7-65 

hes $star. 7-113 


hes $star_dir_list_ 7-120 
hes $star_list_ 7-115 
match _star_name_ 7-150 

Start_up.ec 3-4 

statement map —B-16 

static section 1-2, 1-15 


static storage 
see also relocation 


status ; 

access control 

hes $get_user_effmode 7-93 

msf_ _manager __ $acl_list 7-162 
directory 

hes $get_author 7-81 

hes $get_dir_ring_ brackets 

hes $get_safety_sw 7-88 

hes _$quota_ read 7-102 

hes $star_ dir list_ 7-120 

hes $star_ list 7-115 
directory contents 

hes $star_ 7-113 
messages 

active _fne_err 7-3 

condition _interpreter_ 

convert status_ code_ 
object segment 

object_info_$brief 7-166 

object_info $display 7-166 

object_ info _$long 7-167 
resource usage 

hes $get_process_ usage 
segment 

hes $get_author 7-81 

hes $get_be author 7-82 

hes  $get_ max _length 7-85 

hes _$get_| max _length_ seg 7-86 


7-21 
7-28 


7-86.1 


7-83 


status (cont) 
segment 
hes $get_ring brackets 
hes $get_safety_sw 7-88 
hes  $get_ safety_ sw seg 7-89 
hes $get_uid_ seg 7-92.1 
system information 
system_info_$abs_ chn 7-197.1 
system_ info “$abs_ _prices 7-199 
system_ info ~$device prices 7-196 
system_ info “$installation_ id 
7-193 
System_info $io_prices 7-199 
system_ info ~$last shutdown 7-200 
system_ info ~$next_ shift_change 
7-198 
system_info_$next_shutdown 7-= 
system_info $prices 7-195 
system_ info _$shift_ table 
system_ info $sysid 7-193 
system_ info _$timeup 7-194 
system_info $titles 7-193 
system_ info _$users 7-194 


7-87 


195 
7-198 


storage 
based 
get_system_free_area_ 7-71 
storage classes 
automatic 2-1 
internal 1-2 
internal static 
static 1-15, 


1-29 
ino 4. 258 


Storage quota 
hes $quota_move 
hes ~$quota_ read 


7-101 
7-102 
Subroutine calling sequences 2-9 
subroutines 
error messages 
Sub_err_ 7-186 
symbol block 


1-23, 1-33 


symbol blocks B-1 


symbol section 


symbol block 
symbol header 


132) 12203 13235 4231; 
1-21 


1-20 


symbol table 
data type codes B-15 
entry info block B-7 
free-format B-1 
PL/1 runtime symbol table 
runtime block node B-4 
runtime symbol node B-7 
runtime token node B-4 
statement map B-16 
symbol block B-1 


B-3 


system information 


system_info_$resource price 7-197 
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telephone 
auto call channel 
dial_manager_$dial_out 
dial_manager_ ~eall ~ 6-38 


7-49 


terminal 
printing 
dump_segment_ 7-56 
terminals 
multiple 
dial_manager $allow_dials 7-48 
dial _manager ~$registered_ server_ 
7-49 
dial_manager_call 6-38 


terminate process 7-202 


text relocation codes 1-28 
text section 1-1, 1-23, 1-31, 
entry sequence 1-2, 1-27 
gate entry point transfer vector 

1-2 
structure of 1-2 


1-32 


time 
last system shutdown 


system_info_ $last_shutdown 7-200 
next system shutdown 

system_info_$next shutdown 7-195 
process CPU usage 

system_info_ $abs prices 7-199 

system_ info _$prices 7-195 

timer_manager_ $cpu_call 7-204 


timer _manager ~$epu_ call inhibit 
7-205 
timer_manager_$cpu_wakeup 7-205 
timer _Manager_. ~“$reset _cepu_call 
7-205 
timer_manager_$reset_cpu_wakeup 
7-205 
real time 
system_info_$prices 7-195 
timer_manager_$alarm_call 7-203 
timer _Manager_| _$alarm_ call inhibit 
7-204 
timer_manager_$alarm_wakeup 7-204 
timer manager $reset alarm call 
7-206 ~ - ~ 
timer_manager_ $reset_alarm_wakeup 
7-206 
shift change 
system_info_$next_shift_change 
7 41 
{= 3 
system startup time 
system_info_ $timeup 7-194 
timer_manager_ 
timer_manager_$alarm_call 7-203 
timer. _manager __ _$alarm_ call_ inhibit 
= ecu 
timer_manager_$alarm_wakeup 7-204 
timer _manager _$epu_ call 7-204 
timer manager _$epu_ call inhibit 
7-205 


timer_manager_$cpu_wakeup 7-205 


timer_manager_ (cont) 

timer _manager _ $reset_ alarm_call 
7-206 

timer_manager_ $reset_alarm_wakeup 
7-206 i 7 

timer_manager_ $reset_cpu_call 

timer _manager _ ~$reset _cpu _ wakeup 
7-205 


7-205 


timer_manager $sleep 7-203 
translators 
storage system 
tssi_$clean_up_ file 7-211 


tssi _$clean_ _up_segment 7-211 
tssi _$finish_ file 7-209 
tssi _$finish_ _segment 7-208 
tssi _$get_ file 7-208 
tssi_$get_segment 7-207 
trap word 1-12 
type pair 1-10 
U 
unwinder _ 7-212 
usage 
segments 
mhes $get_seg_ usage 7-156 
mhes _$get_ seg_usage ptr 7-156 
user 
parameters 


get_privileges 7-68 


validation level 
directory 


hes $get_dir_ring brackets 7-83 
hes $set_dir_ ring brackets 7-105 
segment 
hes $get_ring brackets 7-87 
hes $set_ring brackets 7-110 
W 
wakeup 
process CPU usage 
timer_manager_$cpu_wakeup 7-205 


timer _manager _ ~$reset _cpu_wakeup 
7-205 
real time 
timer_manager_$alarm_wakeup 7-204 
timer | _Mmanager _. _$reset_ alarm_wakeup 


7-206 
working directory 
default 
change default_wdir 7-16.2 
get default _wdir_ 7-62 


search rules 
hes $get_search rules 7-90 


hes | _$initiate_ search_ rules 7-95 
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